I have discussed in previous articles that Sage CRM REST service represents the objects exposed in Sage CRM (Company, Case, Quote etc) as resources. This means that a unique URL identifies each resource.
A Sage CRM REST API URL will follow a basic pattern.
So if we are interested in the 'Company' table as a resource then we could use URLs such as the following:
- http://myserver/sdata/crmj/sagecrm2/-/company('43')
- http://myserver/sdata/crmj/sagecrm2/-/company?where=comp_companyid in ('43', '45')
- http://myserver/sdata/crmj/sagecrm2/-/company(comp_companyid eq '962')
And these examples above have provided a way of specifying each record (Entry) or set of records (Feed) that is being accessed.
The use of a URL to identify each resource is then coupled with standard HTTP methods. The REST API uses common HTTP methods to indicate the action within the system.
- GET - reads data and doesn't change application state
- POST - creates resources and queries for data using conditions
- PUT - updates resources
- DELETE - removes resources from the database
The best way of understanding how the API allows the API methods to be used is by looking at the examples provided in the documentation.
The documentation team has created Postman collection (https://www.getpostman.com/collection) demonstrating how to create, retrieve, update, and delete Note records in Sage CRM. A Postman collection is an executable API description and shows clearly how to use the API.
Below is a screenshot showing a simple request to list all the notes within the system.
And another to show how to select a single record.
In both the examples above the requests 'worked' and the data was returned with an HTTP status code of 200. Along with the HTTP status code, there is a JSON payload returned in the response body.
This response is going to be one of either 3 types.
An entry: this is the representation of an individual resource and contains the native, JSON formatted objects
A feed: is a collection of entries
A diagnosis: is returned when something goes wrong with the request
The HTTP status codes are divided into four major categories:
200 - Success
300 - Redirection
400 - User error
500 - Server error
And just considering the first 3 types these can provide much information.
The diagnosis codes can provide very useful information that can be dynamically consumed by any client application.
In the image below you can see that an attempt has been made to delete a record that does not already exist in the database.
Whether we want to insert, update, delete or simply view data the documentation provides for each of the supported entities a full set of examples of how to build the necessary JSON packages and the results that may be expected.