We have updated the REST documentation and guides for Sage CRM 2022 R1 to provide guidance on how the Sage REST API generates its responses and the control of those available to developers.
The Sage CRM REST API follows the design of any RESTful system. The REST API provides a uniform interface for developers to allow the manipulation of resources. The 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 so that you can manipulate it with standard HTTP methods.
The Sage CRM API is a "hypermedia-driven API" - This means that the Sage CRM REST API returns responses that include links to resources available in Sage CRM.
The requesting client should then be able to use the server-provided links contained in the response to the REST request to dynamically discover all the available resources it needs.
This means that if you request a company resource the results should provide the endpoints that can be used to discover the persons, the opportunities and cases linked to the company resource.
The jargon word for this is "HATEOAS" which stands for "Hypermedia as the Engine of Application State". This is quite a horrible word and could easily confuse anyone.
I have written previously about HATEOAS in the article Understanding the data available within the REST API.
A customer had a question
"I make a request to retrieve prototypes over HTTPS and the links in the results point to HTTP and a different server name".
The problem the custom had was this
They requested
https://www.mycompany.com/sdata/crmj/sagecrm2/-/$prototypes
In this case, the customer had been addressing using the HTTPS protocol and had used the fully qualified domain name (FQDN) - using both the hostname (www) and the domain name (mycompany.com).
And the results contained links e.g. $baseUrl that pointed to
http://prodservcrm/sdata/crmj/sagecrm2/-/
and
http://prodservcrm/sdata/crmj/sagecrm2/-/$prototypes/Address
etc
When a REST client requests a resource that uses such and such an address BUT the results come back pointing at a different address path can be disconcerting.
There are two points to understand:
- Sage CRM will always return HTTP - the expectation is that the webserver will redirect HTTP calls to HTTPS using a page rule or root configuration of the webserver.
- Sage CRM builds its REST paths using the settings contained in System Parameters "ServerNames" list.
You can see this in the database:
SELECT Parm_Value from Custom_SysParams where Parm_Name='ServerNames'
To ensure that the FQDN is used in the response URLs a developer needs to ensure the desired address is the first entry in the list.
The documentation on developer.sage.com has been updated with guidance on how to do this.
