Getting started with the Synergist API

CONTENT

• [What is an API?] (#locallink_whatisanapi)
• [Who might use an API?] (#locallink_whomightuseanapi)
• [JSON] (#locallink_json)
• [Making an API request] (#locallink_makinganapirequest)
• [Formatting an API response] (#locallink_formattinganapiresponse)
• [Deconstructing an API request] (#locallink_deconstructinganapirequest)
• [Deconstructing an API response] (#locallink_deconstructinganapiresponse)
• [Creating a record] (#locallink_creatingarecord)
• [Receiving a response] (#locallink_receivingaresponse)
• [Updating a record] (#locallink_updatingarecord)
• [Appendix 1] (#locallink_appendix1)
  
  

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.

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.

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

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.