API Reference

Versioning

How the Operations1 REST API handles versioning

API Versioning at Operations1

📘

Subscribe to our Developer-Newsletter to stay ahead.

We provide you with updates regarding new versions and breaking changes through our Developer Newsletter.

🚧

'Accept-Version' is a required header!

In case you came here because you have got this returned:
{"message":"Include 'Accept-Version' header with the desired API version.","errorCode":"PG3"}
Our API requires the version in the request header, meaning the Accept-Version: yyyy-MM-DD header must be set! Read more on this below

Why Versions

API versioning is essential for us as the API provider to maintain compatibility and stability while making improvements to our service. It allows us to introduce changes gradually and enhance features without causing disruptions for our valued API consumers. This approach offers flexibility, ensuring that we cater to various needs, maintain backward compatibility, and reduce downtime. We're committed to fostering excellent developer relations by providing clear transitions and thorough documentation for each version. Furthermore, we communicate Breaking Changes via our Developer Newsletter, giving you at least three months to switch to new versions and ensuring a seamless developer experience.

Version Format

Our API versions adhere to the format YYYY-MM-DD (year-month-day) to provide clarity and transparency. You may also choose to use the latest version for the most up-to-date functionality. Do not use latest in a production environment as it will fall forward automatically to the latest released version.

📘

Where do I find availabale Versions?

To see the most recent version, look no further then the top left of your screen! If you need more, check our Changelog.

Fixing a Version

By making your app version aware, you anchor your code to a specific set of features that are guaranteed to behave in the same way for the supported timeframe. You have to provide the version number by setting the Accept-Version header.
Here's a sample request to illustrate how to apply a fixed version:

curl -X GET "https://api.operations1.app/tenants/your-tenant-id/users"
-H "Accept: application/json"
-H "Accept-Version: 2023-09-18"
-H "Authorization: Bearer YourAccessToken"

Managing Change

We value your integration and aim to keep it as smooth as possible. Any releases and breaking changes to the Operations1 API are communicated via our Developer Newsletter. When we release a new version, we are supporting the deprecated version for at least an additional three months. This transitional period is designed to provide integrators with ample time to smoothly transition to the latest version of our API.