Versioning

We periodically release new, dated versions of the API whenever we make breaking changes. Although we try to only make backwards-compatible changes, sometimes we have to make a breaking change to iterate on the API.

We consider the following changes backwards compatible:

  • Adding new API endpoints
  • Adding new optional parameters to existing endpoints
  • Adding new data elements to existing responses
  • Adding new response codes
  • Adding new enum values
  • Changing the length or content of any API identifier

Our current version is 2021-03-01.

The Railz-API-Version header must be set for every single request to our API.

📘

If no API version is specified either when initializing a client library or manually as a request header, the API will default to the latest version of the Railz API.

If a change is not backward-compatible, then it is your responsibility to upgrade your code within the deprecation notice period.

🚧

Deprecation Notice Period

Changes are announced, and made, on the first week of each month. Between the date of announcement and deprecation, there are 120 days for you to upgrade your code.