Breaking change policy

Ocrolus strives to continually improve service and enhance our APIs over time.
To that effect, we routinely make changes to our customer-facing APIs, this consists of:

• non-breaking changes
• breaking changes

No advance notice for non-breaking changes

To continually improve our services, Ocrolus may regularly introduce non-breaking changes (as defined below) to any endpoint at any time, with no advance notice.
It is critical for clients to build integrations that handle non-breaking changes.

Advance notice for breaking changes

Ocrolus may introduce breaking changes (see below) at any time. Such changes exclusively involve the removal of access to existing endpoints.

Ocrolus will notify clients at least 60 days prior to a breaking change. During this 60 day notice period, Ocrolus may provide an alternative endpoint for the transition.
The alternative endpoint may be more limited than the previous endpoint.

In practice this means:

• To the best of its abilities, Ocrolus will never make a change that 'breaks' any single endpoint.
• For changes that do break a logical endpoint, Ocrolus will provide:
  • A new version of the endpoint
  • A notice
  • A cutover period where both endpoints are supported
  • Final removal of the old endpoint

Terms

Within the context of this document, we use the following definitions:

Object

An object roughly corresponds to a JSON object; a key-value based data structure.

Array

An array is a list data-type that may contain zero or more members.

Field

A field refers to an input that consumers of an API provide.

Non-breaking change definition

Formally, a non-breaking change is a change that does not fit the description of a breaking change.

Examples of non-breaking changes include:

• Adding fields to an object in the response.
• Adding members to any array in the response.
• A change to the response time of the API.
• Additional support of other data-formats (as selected by the Content-Type header).
• Reordering of members in any array in the response.
• Reordering of members in an object in the response.
• Making mandatory input fields optional.
• Adding optional fields.

Breaking change definition

A breaking change consists of two parts:

• Identifying what constitutes a breaking change for the fields (inputs/arguments/parameters to API endpoints).
• Identifying what constitutes a breaking change for the outputs (responses) of the API endpoints.

Breaking change to the input of an API endpoint

This is a change that makes a set of field values for an endpoint invalid, such as:

• Changing the expected datatype of any field.
• Changing an optional field to be a mandatory field or a mandatory field to be optional.,
• Adding additional optional fields.

Breaking change to the output of an API endpoint

This is a change that removes, renames, or moves any piece of data within the response for a given set of field values. Conceptually, the JMESPath to any piece of data in a response for a given set of field values always works. The order of members in any array is not meaningful. However, this is not how Ocrolus formally defines the policy.

Examples of breaking changes:

• Removing a member from an object in the response.
• Renaming a field in an object in the response.
• Removing a member from an array in the response.
• Modifying the data type of a field. For example, converting an array of IDs to an array of objects.

📘

Note

The following are not breaking changes:

• Adding members to an object in the response.
• Adding members to an array.