How Sugar REST API versioning works

Sugar v11 REST API

In order to support some cool new dashboard features, we made some enhancements to our Dashboard APIs in the Fall '17 release. So we added a new REST API version, v11, in that release in order to ensure clients and integrations that were using the existing v10 Dashboard APIs would continue to work properly. For more details on the v11 API, we recommend you check out a recording of our recent Fall '17 release developer webinar and the related migration guide.

Today we won't focus on version 11 specifically but instead on how the Sugar platform will be handling REST API versioning in the future. So read on!

Passing API version using HTTP Header

For REST v10 and our older web services frameworks, the API version was specified exclusively via the URL.

Example 1)

GET <sugar>/rest/v10/me

In the Fall '17 (7.10) release, we introduced an additional way to specify the API version: using an HTTP header. This change allows resource URLs to be treated as unique identifiers to resources regardless of the API version in use.

The REST API version can now be specified via HTTP Accept header. The REST API version should be specified in either the URL or in the HTTP Accept header but not in both locations at once. This new method of specifying the API version in the HTTP Accept header better adheres to RESTful architectural principles. By essentially encapsulating the API version as part of media type, a single resource at a given URL could offer multiple representations using different data formats and API versions.

Example 2)

GET <sugar>/rest/me
...
Accept: application/vnd.sugarcrm.core+json; version=42

We recommend that client start specifying the API version in the Accept header instead of as a component of the URL. Sugar clients will adopt use of the Accept header in the future.

Future use of semantic versioning in REST API

As you probably have noticed, the REST API version is a property of the Sugar REST API as a whole and not individual endpoints.

We plan to implement a semantic versioning policy with MAJOR.MINOR format for the REST API next year.

The version will be specified in the request Accept header as MAJOR.MINOR (ex. 11.1) whereas the version in the endpoint url will be specified as MAJOR_MINOR (ex. 11_1).

The Sugar REST API MAJOR version will be incremented for each Sugar release where compatibility is being broken on any endpoint. The Sugar REST API MINOR version will be incremented for each Sugar release where an API endpoint is changed or additional API endpoints are being added without breaking compatibility.

Not every new Sugar release will result in new REST API versions. Our intent is to only add new features or make breaking changes to our REST API only when it is not possible or prudent (ex. for performance reasons) to do so with the current API.

When there is a breaking change, older API versions should continue to work as-is. For example, if a parameter was removed in newer version, the old version should still support that parameter.

What are breaking and non-breaking changes?

We want to be clear about what we consider to be an API breaking change and what is not.

Breaking Changes

• Removing or renaming an endpoint, a request parameter, or a fixed response field
  • For example, removing the GET /rest/v10/<module> endpoint or renaming the _acl field to _access_control.
• Removing support for a HTTP request method on an endpoint
  • For example, changing from PUT to PATCH method for updating records.
• Change in type for a request parameter
  • For example, a change from an Integer to Decimal value.
• Change in response field format
  • For example, a change in encoding for a response field from plaintext to base64.
• Semantic changes to request parameters
  • For example, a change from treating the % symbol as a literal instead of as a wildcard or a change in default value.
• Semantic changes to an API endpoint
  • For example, an endpoint that was documented to return all records by default and now returns no records by default.

Non-breaking Changes

• Metadata related changes in behavior
  • For example, when Sugar metadata (Vardefs, Viewdefs, etc.) changes are introduced during a Sugar release or as a result of a customization then REST API responses can vary as a result.
• Adding a new endpoint
  • For example, adding a GET rest/Accounts/:id/map endpoint.
• Adding a parameter to a request
  • For example, adding a boolean parameter called shorten_text that decides if long text fields are shortened to 200 characters.
• Adding a field to a response
  • For example, adding a _self field with link to resource URI in GET responses.
• Adding support for another HTTP request method
  • For example, adding support for PATCH method to an endpoint.

If you ever encounter a situation where there is a breaking change on a particular API version between future Sugar releases, then please report those issues via the Sugar Support portal.

Deprecation process for old API versions

Old REST API versions will continue to be supported until at least one year after they have been deprecated. We want to exercise good judgement on how quickly we remove old API versions but please understand that SugarCRM cannot indefinitely support an unlimited number of REST API versions.

What should you do?

1. When building new Sugar clients or integrations or updating existing ones, adopt the latest available REST API version possible in order to take advantage of all the latest features.
2. Use the HTTP Accept header to specify REST API version when using Sugar Fall '17 release or later.
3. Monitor the release notes and documentation on each new Sugar release for deprecation notices on old API versions. Keep our customers safe by planning ahead!