If you haven't seen it already, you can take a look at our Getting started with Gearset API guide, and our full API reference provides full details of the endpoints that Gearset exposes.

API Versions

Gearset periodically versions its API, allowing users to continue using older versions until they're ready to migrate to the latest version.

Our API versions only use major version numbers (e.g. 1, 2, 3), starting at 1 and incrementing when breaking changes are introduced (e.g. 1 -> 2 -> 3).

Specifying the API version

You can specify the API version in the request header api-version; it defaults to 1 if no version is specified.

Example curl command containing the API version:

curl -H "api-version: 1" -H "Authorization: token 052E08E9B1580A0D15121B6009B7C8D9D2ECAED75F888DC53F2D72A86ED575C9"

Specifying an unsupported API version results in an error message like the following:

{
    "Error":{
        "Code":"UnsupportedApiVersion",
        "Message":"The HTTP resource that matches the request URL
              '...' does not support the API version '...'",
        "InnerError":null
    }
}

Checking API versions

The supported API versions can be checked in the response header api-supported-version, as the following example shows:

api-supported-versions : 1, 2, 3

Breaking Changes

Since Gearset versions the API whenever breaking changes are introduced, you might wonder what constitutes a breaking change. The following lists show some of the changes we either do or don't consider to be breaking changes.

Essentially, if your code has to change in order to keep functionally equivalent behavior, we consider that to be a breaking change.

Examples of breaking changes

Changes related to resources
- Removing an existing resource.
- Changing the behavior of an existing resource.
Changes related to headers
- Adding a required request header.
- Removing or renaming an existing request header.
- Removing or renaming an existing response header.
Changes related to requests
Please note that 'parameter' here refers to path parameter, query parameter, and request body parameter.
- Changing an existing request path.
- Adding a required parameter.
- Adding an optional parameter where its default value results in behaviors that do not match previous behaviors.
- Changing an existing parameter from optional to non-optional.
- Changing the default value of an existing parameter.
- Introducing different/stricter validation rule(s) to an existing parameter.
- Removing or renaming an existing parameter.
Changes related to responses
- Adding a new property.
- Adding, renaming, or removing enum values used in a response.
- Changing the type or format of an existing property.
- Removing or renaming an existing property.
- Changing a successful status code (e.g. from 200 to 201).
Other changes
- Introducing a more stringent rate limit.

Examples of non-breaking changes

Changes related to resources
- Adding a new resource.
- Fixing a bug in an existing resource.
- Improving the performance of an existing resource.
Changes related to headers
- Adding a new response header.
Changes related to requests
Please note that 'parameter' here refers to path parameter, query parameter, and request body parameter.
- Adding an optional parameter where its default value results in behaviors that match previous behaviors.
- Introducing more lenient validation rule(s) to an existing parameter.
Changes related to responses
- Changing the order of properties.
- Changing an existing error message.
- Changing an unsuccessful status code (e.g. from 400 to 500).
Other changes
- Introducing a more lenient rate limit.