API versioning

With any rapidly evolving API like Check’s, occasionally breaking changes need to be made. Up until now, we've dealt with this by closely coordinating with each of our Partners to ensure that they have made the necessary changes on their end before we release any breaking change. However, we've known that this was not a scalable solution for any party.

To solve these issues, we're happy to announce that the Check API is now versioned. This means that going forward, we will periodically release one or more breaking changes as a new API version, and each Partner can choose to adopt the new version at their own pace. We will also be recording each version and the changes associated with it in our new API Changelog as they are released.

Breaking Changes

We define a breaking change as any change which has the potential to result in unexpected behavior or errors being returned from API requests that work as expected before the change.

A few examples of changes we would consider to be breaking changes:

• Adding a required request parameter
• Changing a request parameter from optional to required
• Removing a request parameter
• Removing a field from a response body
• Adding a validation rule to a request parameter

Conversely, we would not consider these changes to be breaking changes:

• Adding an optional request parameter
• Adding a new API endpoint
• Adding a field to a response body
• Changing the ordering of fields within a response body
• Removing a validation rule from a request parameter

Naming Convention

The naming convention for our API versions will be to name each version using the ISO-8601 date on which the version was released.

What this means is that we now accept a header named Check-Version with all requests made to the Check API. Clients can set this on their request to have it be handled by a specific version of the API.

We also now keep track of a default API version per Partner, which allows requests from that Partner to use a certain API version by default if no version is included with the request via the Check-Version header. The default API version for each Partner is initially set to the most recent API version available when their account is created in our system. If a Partner would like to change their default API version, today they can reach out to our support team, but we also plan on adding a self-serve option for that soon!

Sandbox vs. Live

We support setting different default API versions for our sandbox and live environments, so Partners can choose to change them independently from one another.