Ocrolus strives to continually improve service and enhance our APIs over time. To that effect, we routinely make changes to our customer facing APIs. Changes to Ocrolus’ customer facing APIs are classified into two sections: non-breaking and breaking changes.
No Advanced 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.
Notice Period for Breaking Changes
Ocrolus may introduce breaking changes (as defined below) at any time. Such changes will exclusively involve 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, an alternative endpoint may be provided for transition (the alternative endpoint may be more limited).
In practice this means:
- Any single endpoint will, to the best of Ocrolus’ abilities, never have a breaking change.
- Breaking changes to a logical endpoint will involve a new version of the endpoint being made available, a notice and cutover period where both endpoints are supported, and finally the old endpoint being removed.
Terms
Within the context of this document, we use the following definitions:
Object
An object roughly corresponds to a JSON object; that is key-value based data structure.
Array
An array is list data-type, which may contain zero or more members.
Field
Field shall be used exclusively to refer to an input provided by consumers of the API.
Non-Breaking Change Definition
Formally a non-breaking change is any change that does not fit the description of a breaking change (above). Some examples of non-breaking changes include:
- Addition of fields to any object contained in the response.
- Addition of members to any array contained in the response.
- Any change in 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 any object in the response.
- Previously mandatory input fields made optional.
- Addition of optional fields.
Breaking Change Definition
Our breaking change definition can be segmented into two pieces: identifying what is considered a breaking change for fields (inputs/arguments/parameters to API endpoints), and what is considered a breaking change for the outputs (responses) of the API endpoints.
Inputs
A breaking change to the input of an API endpoint is defined as a change to the expected datatype of any field, or changing of any previously optional field to mandatory. More broadly, a breaking change is where any set of field values for an endpoint that was previously considered valid, is made invalid.
Importantly this means previously mandatory fields may be made optional, and additional optional fields may be added.
Outputs
A breaking change to the output of an API endpoint is defined as the removal of, renaming of, or moving of any piece of data within the response for a given set of field values. Conceptually, this can be thought of as the JMESPath to any piece of data in a response for a given set of field values will always work, with the exception that the order of members in any array is not to be considered meaningful (though this is not how we define our policy formally).
Importantly this means adding members to any object contained within the response, or adding members to any array, is not considered a breaking change.
Examples of breaking changes:
- Removal of any member from any object contained in the response.
- Rename of any field in any object contained in the response.
- Removal of any member from any array contained in the response.
- Modification of the data type of a field (for example, array of IDs converted to array of objects).