Versioning

Aurora releases a new API version when we make backward-incompatible changes to the Aurora API. Your Aurora API version controls the API behavior you see and is set the first time you make an API request. When we change the API in a backward-incompatible way (something that you can expect to happen at least once a year), we release a new dated version and support it for a minimum of 12 months. To avoid disrupting your integration and breaking your code, we don’t change your version automatically. It is your responsibility to upgrade when you are ready.

Backwards-compatible changes

Aurora defines the following types of changes as backwards compatible:

  • Adding new API resources
  • Adding new optional request parameters to existing API methods
  • Adding new properties to existing API responses
  • Changing the order of properties in existing API responses
  • Changing the length or format of opaque strings such as object IDs, error messages and other human-readable strings
  • Adding new event types to webhooks. Webhook listeners should gracefully handle unfamiliar event types
  • Adding new values to enumerations such as a new component_type in the bill of materials

Additionally, we recommend avoiding assumptions about anything not specified in our documentation. For example endpoints that return arrays do not guarantee order unless explicitly stated in the documentation.

Upgrading your API version

We continually evolve the Aurora API by making non-breaking changes to the current version. If you’re running an older version of the API, upgrade to the current version to take advantage of new functionality and improved performance. When you are confident that your code can handle the current API version, use the Upgrade API or upgrade your version in the Aurora app. Upgrading your API version will affect the parameters you can send and the structure of objects returned for the API calls. A version upgrade switches the version used by API calls that don’t have the Aurora-API-Version header.

To upgrade your version in the Aurora app, navigate to the API Tokens page in Settings, then select the upgrade button, as shown below. You can upgrade each of your API keys independently.

Testing a new API version

To test a newer version for API calls, set the Aurora-API-Version header. You can set the Aurora-API-Version header to the latest available version only.

Rolling back your API version

For 120 hours after you have upgraded your API version, you can safely roll back to the version that you were upgrading from using the Rollback API, or by selecting rollback from the dropdown menu on your key.

Staying informed

We publish information about non-breaking changes made to the current API version and announcements about new API versions to the API product changelog. Subscribe to RSS updates to be notified about new changelog entries: