The release of Sage CRM 2019 R2 introduces a new REST API (v1.0.0 beta) for developers and integrators. This new API enables developers to create, read, update, and delete entities in Sage CRM using standard HTTP methods such as GET, POST, PUT, PATCH, and DELETE.
To be able to start work with the REST API we need to confirm that the endpoint is available. The easiest place to do this is within the Administration screens.
Administration -> System -> System Health
The REST API uses an endpoint called SData 2.0 and this needs to be running correctly for the API to be available.
Sage CRM has a hybrid architecture. The older APIs such as the SOAP web services are directed at the eWare.dll ISAPI extension but the REST interactions will be processed by the Java Web App running under Apache Tomcat.
The endpoint that requests will be directed towards follows a pattern made up of the server, the installation name and the resource within Sage CRM that is being accessed.
Additional path fragments allow identification of either a single entry or feed.
http://[servername]/sdata/[instancename]j/sagecrm/-/company(comp_companyid eq '43')
http://[servername]/sdata/[instancename]j/sagecrm/-/company?where=comp_companyid between 43 and 50
http://[servername]/sdata/[instancename]j/sagecrm/-/company?where=comp_companyid eq '43'
The use of different HTTP methods implies a different action that can be taken on the data.
For example, to retrieve the company Gatecom then the request would need to combine a path that included the required specifier below with a 'Get'.
HTTP Method: 'Get'
To delete the company Gatecom then the request would need to combine a path that included the required specifier below with a 'Delete'.
HTTP Method: 'Delete'
The documentation contains examples of how to carry out actions on all of the supported entities. To allow you to test and get to grips with the API then you should make use of a REST client. REST clients are essential when developing RESTful web services. You can just use any web browser to test GETs, but REST clients also provide formatted views of XML and JSON payloads which are helpful. With a REST client, it's also easy to perform all of the HTTP verbs/actions such as POST, PUT and DELETE methods.
To help me write these articles I have used a REST Client to perform actions on a CRM instance. For example, a REST client would allow me to copy and paste a payload that was returned by a get that I could then copy and paste into a payload field and make a change to the data. Then could then do a POST back to the RESTful web service to create a new resource or change an existing resource.
These are two very helpful REST clients
Postman is an example of an, especially useful REST client. As part of the documentation of REST API, we have made available a Postman Collection, a set of examples, that can be used to demonstrate CRUD actions on the notes table.
In the next article, I will discuss aspects of security within the REST API. This is will cover how authentication is handled, field-level security and user rights defined by security profiles.