Api get query

Calling a service to get the result of a query for an entity is done by an http GET request.

Calling Syntax

The query request on an entity is done using a GET on the following syntax:
http://SERVER:SERVICE/api1/APPLICATION/CONTRACT/ENDPOINT/ENTITY?representation=REPRESENTATION.$query

Where:

• SERVER:SERVICE is the server address followed by the service number.
• APPLICATION is the application (syracuse, erp, or hrm).
• CONTRACT is the api1 contract (administration or x3).
• ENDPOINT is the endpoint (collaboration or an endpoint associated with an X3 or HRM folder).
• ENTITY is the class name.
• REPRESENTATION is the representation name.

Additional parameter can be added in the format &parameter=value. The parameter that can be given in a query request can be added in a menu item query definition.

For example, if the query is the following:
http://my_server:8124/syracuse/collaboration/syracuse/endPoints?representation=endPoints.%24query&count=100

Result

If no error occurs, the http status 200 is returned. Sending a request that does not return any line is not an error: the status will still be 200, but the "$resources" array will be empty.

Sending a URL that contains an unknown property in the 'WHERE' will return an error on X3 endpoints (500) and be ignored on administration endpoints.

The body will return a payload that includes:
* Some meta-data information. The information that may be present is:
* "$url": the URL called
* "$descriptor": the name of the entity
* "$itemsPerPage": the number of lines requested
* "$totalResults": the number of lines found
* ...

• An array called "$resources" that contains the lines. Every property in the line is listed. If an entity is a reference to another entity, it appears as a sub-entity. Some meta data information may also be present, such as:

  • "$uuid" : a unique ID associated with the line.
  • "$key" : the unique key identifying the line.
  • "$creDate", "$creUser", "$updDate", "$updUsr" : creation and update date and user.

• Additional elements can be present, such as:

  • "$links" to describe navigation links that can be located at the global level on the structure or on every line element.
  • "$properties" to describe meta-data related to the properties.

Example on collaboration endpoint

A call to get the list of the endpoints resource with a maximum number of 100 on a server is:

http://my_server:8124/api1/syracuse/collaboration/syracuse/endPoints?representation=endPoints.%24query&count=100

The result payload is:

{
  "$url": "http://my_server:8124/api1/syracuse/collaboration/syracuse/endPoints?representation=endPoints.%24query&count=100",
  "$descriptor": "endPoints",
  "$startIndex": 1,
  "$itemsPerPage": 100,
  "$totalResults": 3,
  "$ui": ...,
  "$resources": [
    {
      "$uuid": "20a5550c-5412-476d-a4ad-2c85074176ea",
      "$key": "20a5550c-5412-476d-a4ad-2c85074176ea",
      "$url": "/api1/syracuse/collaboration/syracuse/endPoints('20a5550c-5412-476d-a4ad-2c85074176ea')?representation=endPoint.$details",
      "$etag": 1,
      "$creUser": "admin",
      "$creDate": "2013-12-07T13:44:21.304Z",
      "$updUser": "admin",
      "$updDate": "2013-12-07T13:44:21.304Z",
      "$properties": {
        "databaseDriver": {
          "$isMandatory": false,
          "$isHidden": true
        },
        ...
        "menuProfileToRoles": {
          "$isHidden": false
        }
      },
      "description": "SEED folder on demo Syracuse solution",
      "application": "x3",
      "contract": "erp",
      "protocol": "x3",
      "dataset": "SEED",
      "databaseDriver": "mongodb",
      "x3ServerFolder": "SEED",
      "x3SolutionName": "DEMOSYR",
      "applicationRef": {
        "$uuid": "46976d3e-127f-4e66-9cf0-c8fb985b4aa0",
        "$key": "46976d3e-127f-4e66-9cf0-c8fb985b4aa0",
        "description": "X3 ERP"
      },
      "x3server": {
             ...
      },
      "$value": "SEED folder on demo Syracuse solution"
    },
    {
...
    }
  ],
  "$links": {
    "$excel": {
      "$url": ...,
      "$title": "Excel",
      "$type": "application/syracuse-excel-worksheet"
    }
  },
  "$template": {
    ...
  }
}

In this payload:
* "applicationRef" is a reference whose properties (key and description) are defined in the structure.
* "$properties" describes meta data associated with the properties of the entity.
* "$links" describes a unique link that gives access to Excel.

Example on a Sage X3 endpoint

A call to get the list of the TABCOUNTRY resource on a DEMO endpoint on the server is:

http://my_server:8124/api1/x3/$$prod/DEMO/TABCOUNTRY?representation=TABCOUNTRY.$query

The result payload is:

{
 "$itemsPerPage":20,
 "$resources":[
 {
  "$uuid":"81e1d142-2c5b-4c29-b322-e20b9c040a7b",
   "$etag":"2014-12-10T12:27:44Z",
   "CRY":"AR",
   "CRYDES":"Argentine",
   "EECFLG":false,
   "EECDAT":"0000-00-00",
   "CUR":"ARS",
   "CUR_REF":{
    "$title":""
   },
   "LAN":"SPA",
   "LAN_REF":{
    "$title":"Spanish",
    "$description":"Spanish"
   }
  },
  {
   "$uuid":"f3b1e21e-f011-4c78-854b-0f9b90ce97af",
   "$etag":"2014-12-10T12:27:44Z",
   "CRY":"BE",
   "CRYDES":"Belgium",
   "EECFLG":true,
   "EECDAT":"1999-01-01",
   "CUR":"EUR",
   "CUR_REF":{
    "$title":"Euro",
    "$description":"EURO",
    "$symbol":"EUR",
    "$scale":2,
    "$precision":13
   },
   "LAN":"FRA",
   "LAN_REF":{
    "$title":"french",
    "$description":"French"
   }
  },  ...
 ],
 "$links":{
  "$next":{
   "$url":"http://aysyrqav7:8144/api1/x3/hrm/GEMFPROBIS/TABCOUNTRY?representation=TABCOUNTRY.$query&key=gt.BH&orderBy=CRY",
   "$type":"application/json;vnd.sage=syracuse"
  },
  "$last":{
   "$url":"http://aysyrqav7:8144/api1/x3/hrm/GEMFPROBIS/TABCOUNTRY?representation=TABCOUNTRY.$query&key=lt&orderBy=CRY",
   "$type":"application/json;vnd.sage=syracuse"
  }
 }
}

In this payload:
* "$itemPerPage" gives the number of items requested (20 is the default).
* "LAN" is a reference, "LAN_REF" giving the associated properties.
* "$links" describes a two pagination link to get the next and previous page.