Developer Guide
Querying Entities

    Magentrix REST API allows you to perform queries against any of the Entities defined given that the authenticated user has access to the Entity. The query is an “HTTP GET” call that returns an array of results for an entity in JSON format. Queries that are sent to Magentrix must be in a given format with optional values. There are two HTTP parameters that must be passed to Magentrix, which are:

     
    q:  Query an entity in the following format:
     
    {SELECT [field1],[field2] ... } FROM [entityname] WHERE [conditions] {ORDER BY [fieldname] ASC|DESC} {Limit [take],[skip]}

     

    In the above query:

    [entityname] is the name of the entity being queried
    [conditions] is a list of conditions separated by a logical AND and OR.  Precedence can be set by parenthesis. Conditions can use the following operators:
     
    Greater Than: >
    Greater Than or Equal: >=
    Less Than: <
    Less Than or Equal: <=
    Equal: =
    Not Equal: !=
     

    In addition for string fields, the following methods can be used:

     

    String.IsNullOrEmpty([fieldname])

    [fieldname].ToLower()

    [fieldname].ToUpper()

    [fieldname].Contains([string value])

    [fieldname].StartsWith([string value])

    [fieldname].EndsWith([string value])

     

    NOTE: Comparison for string fields in Magentrix is case sensitive.

     

    {ORDER BY} section is optional, if defined however, proceed with field name and it must indicate direction, one of two possible values of ASC for ascending or DESC for descending order.{SELECT} section is optional. If defined it must proceed with one or more fields that are being selected. This statement will result only in a sub-set of fields being returned.

    options:  This is optional parameter. It is in a JSON format as such: <   ="">

    take: Takes n number of records from the result set. Default value is 0, which indicates all records.
     
    NOTE: You may want to limit the number of records being returned from Magentrix to make sure large number of values is not being returned.
     
    Skip: Skips n number of records (NOTE: [ORDER BY] is required for skip).
     
    NOTE: Skip and Take are mostly used in order to perform Pagination.
     
    Includes:Performs eager loading of data on lookup and master detail fields. These field names must be separated by “,”.  By default Magentrix will load 1 level deep, you can load n level deep by using this property. We recommend using Magentrix Entity Browser in order to properly reference the relationship fields. In most case for “standard” entities lookup relationship is postfix with “_r”.  For example if field name is called “AccountId”, the object is will be “AccountId_r”. For Force.com object, the relationship name is the same as the one defined by Force.com. For example, if field name is “AccountId”, the relationship object will be “Account__r”.
     

    Below are some examples of queries to show you how Magentrix queries are formed and their JSON responses. Note that these sample queries run against Salesforce imported objects. However, you can modify these queries to run against Magentrix standard entities as well. 

    This query will return all accounts with “Name” fields that are not null or empty. (Note that Name field in Magentrix can never be empty, therefore this query will return all available records):

    https://<instance>.magentrixcloud.com/rest/2.0/query?q=SELECT Id,Name,CreatedOn,Owner.Name FROM Force.Force__Account WHERE !string.IsNullOrEmpty(Name)    
    -H "Authorization: {token}"    
    -H "Content-Type: application/json"
    
    

    The JSON Response Content will look like:

    {
       "Count" : 3,
       "Records" : [ {
            "CreatedOn" : "2012-05-16 02:09 PM",
            "Id" : "001E000000HUJOaIAP",
            "ModifiedOn" : "2012-05-16 02:09 PM",
            "Name" : "United Oil & Gas Corp.",
            "Owner": {
                Name: "Sam Smith"
            }
         },
         {
            "CreatedOn" : "2012-05-16 02:09 PM",
            "Id" : "001E000000HUJOUIA5",
            "Name" : "Burlington Textiles Corp of America",
            "Owner": {
                Name: "Joe McDoland"
            }
         },
         {
            "CreatedOn" : "2012-05-16 02:09 PM",
            "Id" : "001E000000HUJObIAP",
            "Name" : "sForce",
            "Owner" : {
              "Name" : "Sam Smith"
             }
         }
       ]
    }

     

    The example below returns all accounts that start with capital “B”:

    https://<instance>.magentrix.com/rest/2.0/query?q=SELECT Id,Name FROM Force.Force__Account WHERE Name.StartsWith("B")
     

    The query below finds all accounts that start with “b” or “d” and end with “c”. Note that order of precedence is applied to the query:

    https://<instance>.magentrix.com/rest/2.0/query?q=SELECT Id,Name FROM Account WHERE (Name.ToLower().StartsWith("b") OR Name.ToLower().StartsWith("d")) AND Name.ToLower().EndsWith("c")


    We can now apply options and limitations. We want to skip the first 5 records and take the next then, and we are only interested in the Name and CreatedOn field. Our condition must be that the Name field cannot be null or empty:

    https://<instance>.magentrix.com/rest/2.0/query?q=SELECT Name,CreatedOn FROM Account WHERE !String.IsNullOrEmpty(Name) ORDER BY CreatedOn DESC Limit 10,5
    
    
     

    The JSON Response Content on will look like:

    {
      "Count" : 13,
      "Records" : [ 
          {
            "CreatedOn" : "2012-05-16 02:09 PM",
            "Name" : "sForce"
          },
          {
            "CreatedOn" : "2012-05-16 02:09 PM",
            "Name" : "GenePoint"
          },
          { 
            "CreatedOn" : "2012-05-16 02:09 PM",
            "Name" : "United Oil & Gas, UK"
          }
        ]
    }

    “Records” are the array of records returned, and “Count” indicates how many records match the criteria in total. If Query has no records, the response will look like:

    {
      "Count":0,
      "Records":[]
    }