Sage CRM's publically accessible and documented REST API was introduced in Sage CRM 2019 R2.
If you have been working with Sage CRM for a while then you probably know about and have used the older SData 1.1 API. And while it is true that the REST API has its inception within the SDATA specification it has been taken sufficiently away from that starting point for us to redesignate this as our REST API.
The two APIs have different endpoints and have different internal behaviour.
a) The SData API is ReadOnly and returns XML. b) The REST is full CRUD and data is in JSON format. The REST API generally is simpler in detail but much broader in functionality
We introduced the API with the version number "v1.0.0 beta". But why is this classed as 'beta'? What does the 'beta' status signify?
Sage is fully committed to this API but it is still being developed and extended. This is not a fixed and 'done' API like the existing COM, .NET, SOAP API and even SData API. What I think is exciting about working with the REST API is knowing that the new API is fundamental to all new product feature development by Sage for Sage CRM.
One of the strategic drivers of the Sage CRM Roadmap is the desire to make the product more accessible and attractive to developers to create exciting extensions and integrations for the product. This is placing more emphasis on the APIs. Every change that we make in a release makes an improvement related to Sage CRM integration capabilities. Consider the changes made in Sage CRM 2020 R1 and Sage CRM 2020 R2 where we have incrementally improved the integration with MailChimp. These improvements have also created benefits for other integrations. Here I am talking about the ability to enforce uniqueness of email addresses for contacts and that email addresses can be used as a link with other systems.
Below is an image that talks about potential developments within the REST API.
We are working with a potentially 'moving target'. That explains the Beta classification and why Sage been cautious in describing its usage as supporting only core entities as described in the documentation. We have to think defensively about the experience of upgrades.
If, for example, a Developer 'turns on' access to tables in Sage CRM via the REST API within the customisation screens that are not covered by the existing API then they may risk running into problems in future. If a metadata table, like a workflow table, is enabled as accessible then what would happen if Sage added in a later version of Sage CRM specific metadata behaviour or workflow control behaviour to the API? They may be a conflict. I hope that during implementation if non-core (non-documented) entities are enabled for interaction with the REST API this change is logged and recorded in the system-specific documentation or the 'change control' documentation. You would at least know what you then would need to check when an upgrade happened.
The 'Beta' classification is why the API also has its own guide rather than being rolled up into the Developer Guide. Although I think that another good point to make about the REST API documentation is that it is generated automatically from within the codebase so its 'origin' is very different from the remainder of the 'written' documentation.
There will be changes (additions, enhancements and bug fixes) to the REST API within each release. These changes will be detailed in the release notes. But we won't change the versioning of the API in the next release.