Versioning

Each Seequent Evo API has a version. Evo uses semantic versioning, that is major.minor.patch. Any breaking changes will be released in a new major API version. Breaking changes are changes that can potentially break an Evo integration.

Breaking changes

Breaking changes include the following:

• Removing an entire operation (HTTP method or URL endpoint).
• Removing or renaming a parameter.
• Adding a new required parameter.
• Making a previously optional parameter required.
• Changing the type of a parameter or response field.
• Removing or renaming a response field.
• Removing enum values from request parameters or responses.
• Adding a new validation rule to an existing parameter.
• Changing authentication or authorization requirements.
• Changes to the intended functionality of an endpoint. For example, if a DELETE request previously used to soft delete the resource but now hard deletes the resource.

Non-breaking changes

A non-breaking change is a change that you can adapt to at your own discretion and pace without disruption. We release these as a new minor version that replaces the currently released version. For example, new features are usually added as minor version updates. In most cases, we will communicate these non-breaking changes after they are already made. Ensure that your application is designed to be able to handle the following types of non-breaking changes without prior notice from Seequent:

• Adding an operation (HTTP method or URL endpoint).
• Adding an optional request parameter. The parameter may default to a null value, or a documented default.
• Adding a response field.
• Addition of a new value returned for an existing text or enum field.
• Changes to the order of fields returned within a response.
• Changes to the length of fields.
• Changes to the length of responses.
• Adding an optional request header.
• Adding a response header.
• Removal of redundant request header.
• Changes to error message titles, descriptions, or both.
  We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and the type returned.

• Fixes to HTTP response codes and error codes from incorrect code to correct code.
• Changing the rate-limiting of requests. This includes adding, raising, or lowering the request rate limit.
• Adding HTTP redirects.

4xx and 5xx errors

Given that HTTP error codes may be fixed at any stage, because proxies exist, and because some proxies are outside the control of Evo, clients must expect and handle any 4xx or 5xx error in order to be reliable.

Some errors may become more specific:

• 403 Forbidden may become 402 Payment Required.
• 404 Not Found may become 410 Gone (for a soft delete) or 451 Content Unavailable for Legal Reasons.

Some errors, such as 413 Payload Too Large or 429 Too Many Requests, may be added to protect services.

Specific error handling in clients is preferable to generic error handling: the message for a 410 can be quite different to a 404. Seequent will undertake to give a full list of expected errors. However, changes to this list does not constitute a breaking change.

Please look out for email communication from Seequent where we may notify you about new versions, breaking and non-breaking changes to our APIs. For breaking change notices, the email notice will usually include the future release date of the new major API version as well as instructions on what actions you need to take to update to the new version. To avoid disruption to your users, ensure that you update to the new REST API major version before the support for the old version is removed.