Versioning

We commit to complete backwards compatibility within the major release version. Code written for prior releases will continue to work for subsequent releases within that major version.

Our commitment to backwards compatibility is accomplished by only appending attributes to API payloads and responses. Previously defined attributes will not be modified nor removed.

To take full advantage of this compatibility commitment, you should ensure that your code does not rely upon an exact number of attributes being part of the response. Nor should you expect the field ordering in response payloads to be consistent over time.

Our backend API server is written in Go. To support our commitment to avoid breaking changes, all booleans (whether supplied as parameters to an API call or returned as attributes in an object) are designed such that the default state will be false. This matches Go's definition of the zero value of a boolean.

We anticipate staying on version 1 of our API for a very long time. However, as breaking changes could become necessary, we have preemptively defined an upgrade mechanism to support multiple major versions. When an application is created, it is locked into the then-current major version. This can be changed within the application's settings dashboard or via an API call.

You can also set the major API version on a specific request via the REVHQ-Version header. This header will override the default API version associated with the application. This is most useful as part of QA when migrating between versions.

curl https://api.revenuehq.com/user \
  -H "Authorization: Bearer some-authentication-token"
  -H "REVHQ-Version: 1"