Introduction
When we introduce changes to our API, we follow best practices to have the least disruption on existing integrations. For example, we follow the CQRS concept.
While we strive to reduce the impact on existing integrations, we sometimes have to introduce changes that are not compatible with existing API versions. Doing so enables us to keep our APIs consistent and to improve the quality and developer experience.
When we introduce a breaking or incompatible change, we release a new API version to accommodate the change. This article describes the versioning of the API v2.
This article is not related to legacy API v1 that was phased out.
Checking the API version
You can check the versions of the APIs in the URLs that you use to reach the Perfect Gym platform. Each API URL contains a version suffix starting with either a "v" or "V" character followed by a whole number to indicate the API version. We increment the number for every version.
Here are some examples of different API versions:
https://presentation.perfectgym.pl/api/v2/AccessControl/OpenGate // version 2.0
https://presentation.perfectgym.pl/api//v2.1/odata/ActivityCategories // version 2.1
To check if you're using the latest API version, refer to the version in our API Reference.
Up-to-date API references are available directly within PG instance under https://your-company.perfectgym.pl/Api/Docs/ApiReference/
API version and PG version
API versions are independent of Perfect Gym system version numbers.
As a result, you might use the newest version of API but not be able to use the full potential of the new endpoints due to the fact that your company wasn't updated to the early adopter version yet.
- General release receives regular updates that include bug fixes, stability improvements and security patches.
- On the other side, Early adopters receives also new features (like new endpoints), code refactors and breaking changes.
The system version is updated in regular cadence.
API is an interface to the PG system. Changes that impact PG system behaviour (for example contract transactions calculation methods) may ultimately impact API behaviour.
Non-breaking changes
A non-breaking or backwards-compatible change is an API change that allows your integration to continue using the API without any additional changes on your side. When we introduce new functionalities and changes to our API, we do our best to implement them in a backwards-compatible way. Depending on the type of non-breaking change, we implement it to all or only the highest version of an API.
| Non-breaking changes types | All versions | Only highest version |
|---|---|---|
| Adding a new endpoint | x | |
| Adding an optional field to a request body | x | |
| Adding any field to a response body | x | |
| Adding an optional header to a request | x | |
| Adding a header to a response | x | |
| Changing the case of a header name | x | |
| Changing the value of a header | x | |
| Changing a field from required to optional in a request body | x | |
| Changing a field from optional to required in a response body | x | |
| Changing the text of an error message in a response | x | |
| Add a new HTTP status code for the response | x | |
| Deprecating a request or response field (for documentation) | x |
Breaking changes
A breaking change is an API change that makes your current integration incompatible with the API. To avoid disrupting existing integrations, we introduce breaking changes in a new API version. You can continue to use existing API versions until you are ready to upgrade to the new version.
Breaking changes types:
- Adding a required field to a request body
- Adding a required header to a request
- Removing an existing endpoint
- Removing a field from a request body
- Removing a field from a response body
- Removing a header from a request
- Removing a header from a response
- Changing the HTTP status code of a response
- Changing error codes for an existing error
- Changing a field from optional to required in a request body
- Changing a field from required to optional in a response body
- Renaming a field in a request or response
- Changing the type of a field in a request or response
New API version without changes
In some cases, we may introduce a new API version without visible changes to API consumers. We do so to improve the stability and consistency of our APIs, or to implement some groundwork for bigger changes in the future.
Upgrading to a new API version
In general, we recommend upgrading to new API versions whenever possible. Keeping your integration up-to-date is crucial so you can take advantage of recent developments and improvements in our system. However, if you decide to stay in your current version, you can continue to do so. We maintain older versions of our APIs that you can continue to use until you are ready to upgrade.