Overview
This document defines the Synergist XML/JSON API which is based on REST.
A request needs to include the parameters required for the action being taken. The Synergist username and password or session are always mandatory parameters. The API version number is a mandatory parameter.
For example:
GET /jsonapi/users.json?user=user&password=user&action=newsession&version=3
The above URL would create a new session for the user.
GET /jsonapi/system.json?user=user&password=user&action=version&version=3
The above URL would get system information.
General parameters for all requests:
| parameter | description |
|---|---|
| user | Synergist login ID |
| password | Synergist password |
| page (optional) | Data page to return, page numbering starts at 0 |
| rows (optional) | Number of records/rows to return. 0 = return all rows |
| version | Version of the API – currently 3 |
| username | Alternative Synergist username to use for data retrieval on behalf of a different user |
XML Response
When a response is sent which contains multiple records, the root element of the XML tree will have the following attributes:
| attribute | description |
|---|---|
| TotalRows | this will be the total number of records/rows in the selection, regardless of page requested |
| TotalPages | this will be the total number of pages available, based on the rows parameter supplied |
| MorePages | this will be True if further pages of data are available or False if you have fetched the last page |
In case of any error, the Synergist server will return an HTTP 404 error together with an XML structure containing the error details:
<Responses>
<Error ErrorID="404500">
<ErrorText>invalid action companylist</ErrorText>
</Error>
</Responses>
The following errors are possible for all requests:
| ErrorID | ErrorText |
|---|---|
| 404001 | no credentials supplied |
| 404002 | invalid credentials supplied |
| 404003 | account disabled |
| 404004 | request not recognised |
JSON Response
When a response is sent which contains multiple records, the root of the JSON string will have the following attributes:
| attribute | description |
|---|---|
| totalrows | this will be the total number of records/rows in the selection, regardless of page requested |
| totalpages | this will be the total number of pages available, based on the rows parameter supplied |
| pagenumber | the current page returned in the set |
| pagerows | number of rows requested |
A successful response will contain the following attributes at root level:
| attribute | description |
|---|---|
| Success | true |
| Responsemessage | a context response message |
| Responsecode | response code indicator |
| Errormessage | empty string |
| Errorcode | 0 |
| Data | the root json element containing the data result rows |
A response error will contain the following attributes at root level:-
| attribute | description |
|---|---|
| Success | false |
| Errormessage | any error context message |
| Errorcode | response code indicator |