Versioning

MOST CURRENT VERSION: 2022-10-01

7shifts has introduced API version controls with all v2 endpoints. API versioning allows us to continually improve our API endpoints and provide you with predictable integration into the 7shifts development environment.

To ensure you keep up to date with our changes, check out the changelog and always keep your contact information up to date with us, either by sending us an email to [email protected] or updating your Access Token email address.

How API Versioning Works

Our v2 REST API’s use a x-api-version header with a YYYY-MM-DD version-naming scheme to indicate the API version in every request.

Example version:

Example: OAuth Client API call

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/users' \
--header 'Authorization: Bearer ISSUED_TOKEN' \
--header 'x-api-version: 2022-05-01' \
--header 'x-company-guid: GUID'

Example: Access Tokens API call

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/users' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'x-api-version: 2022-05-01'

Default API Version

All OAuth Clients and Access Tokens are assigned a default version, which are specified in its attributes when the OAuth Client or Access Tokens are created. We use the latest stable release as the default version. If a request is made without the x-api-version, it will fall back to the API version specified in your OAuth Client or Access Tokens. If that API version is no longer supported, it will default to the oldest supported stable version.

You can override the default by explicitly specifying an API version in the x-api-version request header. This enables you to use different versions for different endpoints or use pre-release versions.

You can also contact us to update the default version of your OAuth Client. For Access Token use, the 7shifts administrator portal to update the default version attribute

Release Schedule

Stable versions

7shifts will release a new API version every 3 months at the beginning of the quarter. The version names are date-based to be meaningful as to when they were released (for example 2022-04-01 ). Below is an example of a release schedule for 2022:

Each stable release will be released within 3 days of the first day of the quarter.

Stable versions are supported for a minimum of 12 months and will include security updates only. Functionality changes will be included in newer pre-release or stable versions.

We strongly recommend updating your apps and integrations to the latest stable API version every quarter. You will have 9 months of overlap between two consecutive stable versions to test and migrate your app and implement any changes that affect your app. If there are no changes to the API’s you are using between stable versions, the change will only require you to update the x-api-version request header, or update the default version of your OAuth Client or Access Token(s).

Pre-release Versions

Pre-release versions contain features and changes that are still in progress and may change between stable versions. Generally, these versions are in active development and can expose different features that may not make stable releases. A feature might be added to a pre-release version but then be removed in a subsequent release. These releases are supported for a minimum of 12 months.

We recommend you use pre-release versions to test upcoming changes or access early features. You should specify the pre-release version only on the endpoints you wish to use the early functionality on and use a stable version for all others.

Changes, and security Updates

A new API version release will only be introduced if it includes breaking changes. This includes:

• Making an optional parameter required
• Adding new required parameters
• Request body structure changes
• Response body structure changes
• Removing endpoints
• Depreciation
• Validation rules
• Error codes
• Security fixes

The following non-breaking changes will not result in a new API version. This includes:

• New optional parameters
• Changing required parameters to optional
• Adding new properties
• Adding new endpoints

All changes will be documented in our changelog. If you have questions you can reach out to [email protected] or your partner account manager.

Security Updates

If a security issue is found and it impacts already released API versions, stable or pre-release, 7shifts will take steps to fix the issue on all supported releases. If the issue results in a breaking change, we will notify registered partners and post in the changelog about the security issue and its impact.

Upgrading your API version

We strongly recommend updating your apps and integrations to the latest stable API version every quarter. You will have 9 months of overlap between two consecutive stable versions to test and migrate your app and implement any changes that affect your app.

To upgrade your API version, update the x-api-version request header to the version you wish to use. You can also contact us to update the default version of your OAuth Client. For Access Tokens, use the 7shifts administrator portal to update the default version attribute.

Deprecation Process

Part of an API can be deprecated if it becomes outdated, unsafe or no longer used. It will be marked as deprecated when a new version is released. The deprecation will not be retroactive and will be supported for a minimum of 12 months after deprecation. Deprecated endpoints will be labeled in the developer portal as well as included in the developer changelog.

Webhooks

Versions are currently not implemented in our webhooks. This is an active area of research and it is planned for a future release.