Using JSON

The Exago REST API is JSON-based. Data sent to the API methods is formatted in JSON, and the methods return JSON formatted response objects.

What is JSON?

JSON is a data-interchange format that is designed to be text-based, and easy to read and parse. JSON objects are formatted using the following rules:

1. Objects contain a collection of properties in “key”: “value” format. Braces {} enclose objects.
2. Keys are strings, which are enclosed by single- (‘ ‘) or double-quotes (” “). Each key has a value, indicated by a colon (:). Properties are separated by commas (,).
3. Properties can accept sets of values using arrays, enclosed by brackets [ ]. Values are separated by commas (,).
4. Values can be strings, numbers, arrays, other JSON objects, true, false, or null.
5. The order of properties within an object doesn’t matter.

Example

{
  "users": [
    {
      "id": "358",
      "username": "alex224",
      "admin": true,
      ...
    },
    ...
  ]
}

Using JSON with Code

JSON data usually has to be converted into a format that code can understand. Most modern programming languages have JSON compatible libraries, if they are not built into the language.

To convert JSON strings into objects:

JavaScript (see JSON.parse() at MDN)

var json_obj = JSON.parse('{"user":{"id":"358"}}');

Python 3 (see json at Pydoc)

json_obj = json.loads('{"user":{"id":"358"}}')

JSON Object Documentation

Although JSON objects can be formatted in a variety of ways, each endpoint requires an object with a specific set of properties. The required format can be viewed in the documentation for each endpoint. Some properties are mandatory; some are read-only; some are create-only, which means that they are required for POST calls, but read-only for other call types; and some are optional. Accessing certain resources in an un-authorized state may only return a subset of data; in general we recommend that all REST calls be authorized.

For example, the documentation for the JSON object above might read like the following:

User JSON

Read (-only) permissions indicate that the property cannot be edited with PATCH or PUT. This does not indicate whether a DELETE call can be used on the object.

Using the API with cURL

Throughout the REST documentation there are examples which use cURL, a free command-line tool for using various protocols. Download cURL at: https://curl.haxx.se/download.html. If you’re using Google Chrome, the Advanced REST Client browser extension is an excellent alternative. We recommend using either program to experiment with the API and test the method calls.

API calls using cURL require the following at a bare minimum: Three headers, Accept: application/json, Content-Type: application/json, and the authorization header; The JSON data, which should be empty if the endpoint expects no data; And the “verb” for example POST, GET, etc.

All cURL calls are formatted like the following:

curl http://{webservice}/rest/{endpoint}?sid={sid}&{param1}={value1}&{param2}={value2} ^
	-d "{json}" ^
	-H "Accept: application/json" ^
	-H "Content-Type: application/json" ^
	-H "Authorization: {type} {authstring}" ^
	-X {verb}

Replace text in {braces} with the applicable data for the environment, method, and JSON. End-of-line carets (^) terminate each line to improve readability, but are not necessary.

For example, a new session call is formatted like the following:

curl http://{webservice}/rest/Sessions ^
	-d "" ^
	-H "Accept: application/json" ^
	-H "Content-Type: application/json" ^
	-H "Authorization: Basic Og==" ^
	-X POST

For an un-authenticated installation, you could copy and paste this example into a command line, replacing {webservice path} with the path to the web service, in order to test whether REST is working.

If it succeeds, it should return data similar to the following:

{
   "AppUrl":"ExagoHome.aspx?d={appUrl}",
   "Id":"{sid}",
   "Page":"ExagoHome",
   "ApiAction":"Default",
   "ExportType":null,
   "ShowTabs":true,
   "ShowErrorDetail":true,
   "ReportSettings":{
      "Id":null,
      "ReportPath":null,
      "SortsResource":null,
      "FilterItems":null
   }
}

Note that all the data was returned on a single line. For improved readability, copy and paste this into a “pretty-printer” (there are many free online solutions).

{
  "AppUrl": "ExagoHome.aspx?d={appUrl}",
  "Id": "{sid}",
  "Page": "ExagoHome",
  "ApiAction": "Default",
  "ExportType": null,
  "ShowTabs": true,
  "ShowErrorDetail": true,
  "ReportSettings": {
    "Id": null,
    "ReportPath": null,
    "SortsResource": null,
    "FilterItems": null
  }
}

To pass JSON with cURL, either insert it inline:

curl http://{webservice}/rest/Sessions ^
	-d "{'ReportSettings':{'ReportPath':'TestTestReport'}}" ^
	-H "Accept: application/json" ^
	-H "Content-Type: application/json" ^
	-H "Authorization: Basic Og==" ^
	-X POST

Or reference a text file containing the JSON object:

curl http://{webservice}/rest/Sessions ^
	-d @json.txt ^
	-H "Accept: application/json" ^
	-H "Content-Type: application/json" ^
	-H "Authorization: Basic Og==" ^
	-X POST

json.txt

"{'ReportSettings':{'ReportPath':'TestTestReport'}}"