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.
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:
Example:
{ "users": [ { "id": "358", "username": "alex224", "admin": true, ... }, ... ] }
Note. Ellipses (...) indicate that one or more properties or objects have been omitted for clarity.
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"}}')
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 |
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.
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':'Test\\TestReport'}}" ^ -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':'Test\\TestReport'}}"