API Change Management

In order to continue adding functionality, we regularly make improvements and changes to our API.

Backwards Compatible Changes

We consider the following types of changes to be backwards compatible. You should ensure your code is robust enough to gracefully handle the following changes:

• Adding new API resources.
• Adding new optional request parameters to existing API methods, using sensible defaults if not present in requests.
• Adding new fields to existing API responses.
• Changing the order of fields in existing API responses.
• Changing the length or format of opaque strings, such as object IDs, error messages, and human-readable strings.
• Adding new values to an existing enum.

Versioned Changes

When we make backwards-incompatible changes to the API we will release a new dated version. The current version is 2021-07-28. Changes and upgrade instructions will be detailed in the Changelog.

You must send a Pinwheel-Version header with each request to specify how the Pinwheel API should behave. See Version Headers on the API page for more information.

Old versions are considered deprecated and will be sunsetted when no more API requests are made to them. Trying to use a sunsetted version will result in a 400 Bad Request error.

New dated versions, and plans to deprecate or sunset a version, will be communicated to you by our customer success team. They will also be detailed in the Changelog.

You can access docs for deprecated API versions via the "Versions" menu in the left sidebar.

Terminology

Deprecated: usage is discouraged.

Sunsetted: discontinued, no longer available for usage.

Please contact [email protected] for access to our Developer Dashboard.