Getting started with the Synergist API

CONTENT

What is an API?

API stands for ‘Application Programming Interface.’ APIs are involved in nearly everything we do - working quietly in the background to make it possible to order shopping online, book accommodation, download software and even rate a song. An API is a software intermediary, similar to a middle person, helping web pages and applications talk to each other by delivering requests and responses.


Who might use an API?

Software developers create and use APIs to develop programs. Back-end programmers create APIs that consider all the complex business logic and access rights. Front-end/user interface programmers use APIs to send and retrieve data without the need to understand the back-end coding.

External programmers may wish to run specific tasks from their website or intranet. They can use APIs that have been created and published by the Synergist software development team.

Different APIs perform different actions. To meet the wide variety of client needs, Synergist continuously develops and adds new APIs to the library of commands stored in an API document. The current Synergist API document contains hundreds of APIs and even these do not cover all of Synergist’s functionality.

To view the current and previous versions of the Synergist API document, please refer to: https://apidoc.synergist.co.uk/reference


JSON

The Synergist API uses JSON for communication between the web page/app and the Synergist server.

JSON stands for JavaScript Object Notation. It is a lightweight format for storing and transporting data. JSON is often used when data is sent from a server to a web page. JSON is in human readable form and at its simplest it is a set of name/value pairs.

Examples of JSON field names and values:

{ “name” : “Mike” } { "gender" : "Male" } { "age" : "24" }

For more information about JSON, how it works and how to use it, please refer to: https://www.copterlabs.com/json-what-it-is-how-it-works-how-to-use-it/


Making an API request

An API call to a server is known as a ‘Request’. The information returned is called a ‘Response’.

An API request needs to:

  • Pass information identifying the user making the call (username, password or session token)
  • Specify a command (what to do)
  • Pass data/parameters required to process the request

If the user doesn’t have adequate access rights or permissions to perform the call, the server will return an error. When calling a database, the API call can be either a request for data or an ‘Action’.

A request for data results in data being returned in JSON format, but no changes are made to the database. An ‘Action’ will often result in an update being performed on the underlying data - see below for an example.

Example of a simple non-action API request to acquire a list of users:

http:///jsonapi/users.json?user=user&password=user&style=modeldata&modelstructure=userdetails&version=3.8

Example of a response when a JSON formatter extension is not installed in the browser:

<spanstyle="font-family: Lucida Console; font-size: 10pt">{
"responsecode": 1,
"responsestatus": "OK",
"errorcode": 0,
"errormessage": "",
"totalrows": 118,
"totalpages": 1,
"responsemessage": "",
"pagerows": 0,
"pagenumber": 1,
"success": true,
"data": [
{
"userUuid": "051110E1F2069643953BAB591A426713",
"userTimestampModified": 1559128222,
"userRecordVersionNumber": 1480,
"userUserId": 217,
"userUsername": "Aaron.Dyson",
"userFullName": "Aaron Dyson",
"userInitials": "AD",
"userEmailAddress": "[email protected]"
},
{
"userUuid": "A21A006EAA8EAA48A6FA806BCEEF383D",
"userTimestampModified": 1554289967,
"userRecordVersionNumber": 68,
"userUserId": 181,
"userUsername": "adrish",
"userFullName": "AdrishHussain",
"userInitials": "wew",
"userEmailAddress": [email protected]
}


Formatting an API response

(A) Copy and paste the response into a JSON viewer http://jsonviewer.stack.hu/
or
(B) Install an extension on the browser to automatically format the response. (Please refer to Appendix 1)

Please refer to the ‘DECONSTRUCTING AN API RESPONSE’ section below to see a formatted version of this response.


Deconstructing an API request

http://<SERVER>/jsonapi/users.json?user=user&password=user&style=modeldata&modelstructure=userdetails&version=3.8

```http://

</span>

The IP address or resolvable DNS name. If Synergist is cloud based, replace with https://YOUR INSTANCE CODE.synergist.cloud

jsonapi

Defines the API format as JSON . There is also an XML type.

users.json

The area of the database that needs accessing.

user=user&password=user

Authenticates the person accessing the server. In the above example, both the username and password are ‘user’.

style=modeldata&modelstructure=userdetails

When requesting data, a data model is commonly passed. The data model specifies a set of fields to return. There are usually two models per area – a ‘list’ model and a ‘details’ model. The list model returns fewer fields than the details model.

version=3.8

The API version. With each Synergist release, the API is updated to a newer version. The older API versions still work but more recent features aren’t included.

 

Deconstructing an API response

The first part of the API response is the header, containing information about the number of rows of data.
The subsequent parts of the response are the records returned - in this case, two user records.

{
  "responsecode": 1,                                                     The Header
  "responsestatus": "OK",
  "errorcode": 0,
  "errormessage": "",
  "totalrows": 2,
  "totalpages": 1,
  "responsemessage": "",
  "pagerows": 0,
  "pagenumber": 1,
  "success": true,
  "data": [
    {
      "userUuid": "051110E1F2069643953BAB591A426713",                    Returned record
      "userTimestampModified": 1559128222,
      "userRecordVersionNumber": 1480,  
      "userUserId": 217,
      "userUsername": "Aaron.Dyson",
      "userFullName": "Aaron Dyson",
      "userInitials": "AD",
      "userEmailAddress": "[email protected]"
    },
    {
      "userUuid": "A21A006EAA8EAA48A6FA806BCEEF383D",                    Returned record
      "userTimestampModified": 1554289967,
      "userRecordVersionNumber": 68,
      "userUserId": 181,
      "userUsername": "adrish",
      "userFullName": "AdrishHussain",
      "userInitials": "wew",
      "userEmailAddress": [email protected]
    }

 

Creating a record

For more complex calls such as creating an Activity or a Job record, an ‘action’ must be passed.
‘Actions’ are commands that allow changes to be made to data. Examples of ‘Actions’ include:

  • action=create
  • action=modify
  • action=delete

The API call must specify the action (create/modify/delete) and include parameters and all mandatory fields that need to be passed to the server in a ‘Data array’.

http: //<SERVER>/jsonapi/activities.json?company=1&user=user&password=user&version=3.8&action=create&input={
  "data": [
    {
      "activityActivitytypeCode": "Notes",
      "activityClientCode": "1/BEACHGOL",
      "activitySubject": "My Meeting notes",
      "activityDetails": "Meeting at BoundryMilll",
      "activityCompanyNumber": 1,
      "activityCustomField186": "My Text"
    }
  ]
}

 

Receiving a response

When a record has been created, the server returns key information including the status, a response message and the entity ID of the newly created record.

{
  "responsecode": 1,
  "responsestatus": "OK",
  "errorcode": 0,
  "errormessage": "",
  "responsemessage": "data processed successfully.",
  "warningmessage": "",
  "success": true,
  "data": [
    {
      "activityuuid": "F718837693D3694F00D2A0F50FC67F1A",
      "activityID": 6743,
      "activityOwnerID": 54,
      "activityOwnerName": "User",
      "activityTimeStampModified": 1458753687,
      "activityRecordVersionNumber": 1
    }
  ]
}

 

Updating a record

Updating a record requires an API call that includes:

  • The ‘action’ i.e. action=update
  • The entity ID or ‘UUID’ to identify the record that needs updating
  • The field names and values requiring an update
http: //<SERVER>/jsonapi/activities.json?company=1&user=user&password=user&version=3.8&action=update&input={
  "data": [
    {
      "activityID": 6958,
      "activityDetails": "Meeting at Boundry Mill",
      "activityCustomField300": "MyText"
    }
  ]
}

 

Appendix 1

How to install a JSON Formatter extension in Google Chrome:

  • Open Google Chrome web browser
  • Type ‘Google Chrome JSON Formatter’ in the browser search window
  • From the list of results, select and open the Google Chrome JSON Formatter
  • Click on ‘Add to Chrome’ in the top right of the screen

The JSON Formatter will be added to the browser extensions and will automatically format future JSON responses.