Ocrolus is committed to consistently enhancing our services and APIs. As part of this ongoing effort, we regularly update our customer-facing APIs. These updates contain:

• Non-breaking changes
• Breaking changes

Non-breaking change

Formally, a non-breaking change is a change that does not fit the description of a breaking change. It's a modification that does not disrupt existing functionality or require changes to client code that relies on the API. These changes maintain backward compatibility and ensure that the client can continue to use the API without experiencing errors or needing to update their integrations.

Examples of non-breaking changes include:

• Adding fields to an object in the response.
• Adding members to any array in the response.
• Modifying the API's response time.
• Introducing support for additional data formats, as specified by the Content-Type header.
• Changing the order of members in any array in the response.
• Changing the order of members in an object in the response.
• Changing mandatory input fields to optional.
• Adding new optional fields.

No advance notice for non-breaking changes

To continuously enhance our services, Ocrolus may introduce non-breaking changes to any endpoint at any time without prior notice. Clients need to develop integrations that can handle non-breaking changes.

Breaking change

A breaking change to our API refers to a modification that disrupts existing functionality and requires clients to update their code to maintain compatibility. Such changes can lead to errors or failures in client applications that depend on the previous version of the API. 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.

Advance notice for breaking changes

Ocrolus may introduce breaking changes, which involve the removal of access to existing endpoints, at any time. Clients will be notified at least 60 days in advance of any breaking change. During this notice period, Ocrolus may provide an alternative endpoint to facilitate the transition, though it may offer more limited functionality than the previous endpoint.

In practice, this means:

• Ocrolus strives to avoid making changes that disrupt any single endpoint.
• For changes that do affect a logical endpoint, Ocrolus will provide:
  • A new version of the endpoint
  • An advance notice
  • A transition period during which both the old and new endpoints are supported
  • Final removal of the old endpoint

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 response to 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.

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.