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. In order to use the REST API you need to convert your data to, and from JSON.

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,
      ...
    },
    ...
  ]
}

Note

Ellipses ... indicate that one or more properties or objects have been omitted for clarity.

Using JSON with Code

JSON data usually has to be converted into a format that your 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:

Name	Type	Writeable	Description
users	array of User	yes	List of users belonging to the session

User JSON

Name	Type	Writeable	Description
id	integer	no	This user’s unique Id
username	string	required	This user’s login key
admin	boolean	yes (false)	Whether this user has admin privileges

Note

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 your method calls.

Disclaimer

We cannot provide support for any third-party tools such as cURL or Advanced REST Client.

API calls using cURL require the following at a bare minimum: Three headers, Accept: application/json, Content-Type: application/json, and your authorization header; The JSON data, which should be empty if the endpoint expects no data; And the “verb” e.g. 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}

Note

Replace text in {braces} with the applicable data for your 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 your 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'}}"