menu
Select programming language for code examples

linkVersioning

Our API uses a major-minor versioning scheme, where major versions indicate breaking changes that are backwards-incompatible, and minor versions indicate breaking changes that are backwards-compatible. Backwards-compatible breaking changes are introduced by using a compatibility layer, which is covered more in-depth in this blog post.

  • When we introduce breaking changes to the API that have a compatibility layer, we will release a new numbered minor version. For example, when we released 1.1, which refactored a lot of the distribution API, we added a compatibility layer that maintained compatibility with 1.0's API contracts, such that nothing broke and no changes were needed for customers on 1.0.
  • When we introduce breaking changes to the API that do not have a compatibility layer, we will release a new numbered major version, e.g. we will go from 1.1 to 2.0. We've never done this, but reserve the right to.

Non-breaking changes, such as additions to the API like new endpoints, new resources, and new attributes, will not change the API version.

The current version is 1.6. All changes will be detailed within our changelog.

Only the major version should be provided in the URL, i.e. /v1.

Interested in learning more about how we accomplish this? We've open sourced our API versioning system, request_migrations. It's available as a gem, and the source is available on our GitHub. If you're using Ruby on Rails, check it out!

linkVersion Pinning

When you make your first API request, we will pin your account to the then-current API version. Your pinned API version can be changed via your account settings, e.g. to upgrade a licensing integration from 1.0 to 1.1. This ensures that your integration never breaks, even when we introduce breaking changes to our API.

Alternatively, you may provide a Keygen-Version header to change the API version on a per-request basis. This is useful during upgrades.

The Keygen-Version header should not contain a v prefix.

Keygen-Version: 1.1

We recommend all applications pin their API integration to the current API version. For example, if you're developing an application against 1.1 of the API, we recommend including the above Keygen-Version header in all API requests. Later on, this will make upgrading to e.g. 1.2 much easier.

To reduce breakages, when upgrading, we recommend using the Keygen-Version header. You should only change your account's pinned version after you've confirmed all API requests are using the newer version.

In addition, all webhook endpoints utilize version pinning as well. This ensures that webhook events sent to your endpoints do not change shape.

linkBackwards Compatibility

We will not introduce breaking changes into the API without bumping the current version. In addition, we will support older versions of the API. You can rest assured that the endpoints you're utilizing within your product are stable.

We will never intentionally break an existing API's contract.

Keep in mind that stable does not mean complete. We could potentially add new resources and actions, but existing resources will remain unchanged.

What do we consider to be “backwards-compatible” changes?

  • Adding new API resources.
  • Adding new optional request parameters to existing API endpoints.
  • Adding new properties to existing API resources and responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of resource IDs, future tokens, future auto-generated license keys, or other opaque strings (this includes adding or removing prefixes).
  • You can safely assume resource IDs we generate will never exceed 255 characters (but you should be able to handle IDs of up to that length).
  • Adding new event types (your webhook listeners should gracefully handle unfamiliar events types).
  • Changing undocumented APIs. All undocumented APIs are considered private APIs and are subject to change. All fields not exposed through a public API are considered private and are subject to change.

What do we consider to be "breaking" changes?

  • Changing the structure of API resources.
  • Removing properties from API resources and responses.
  • Deprecating or removing API endpoints.
  • Any other destructive change to the API.

Although we consider these "breaking" changes, these changes can usually be made without disrupting consumers of older API versions, through compatibility layers and deprecations.

As outlined in our versioning strategy above, we will bump the current API version when we introduce a breaking change.