Usually, every API has versioning. Some versions may be deprecated, or no longer supported and obsoleted. Vertopal API is no exception to this rule.
Any change that breaks an endpoint or annoys users to change it quickly, will force us to produce another newer version.
The version of an endpoint is known in its path. A path without a version refers to the latest version, the latest version may be changed in the future and is not stable. so, In the production environment, we recommend that you use the endpoint that clearly specifies the version in its path.
This is also observed in document URLs. That is, an API document page that does not have a version refers to the latest version. but the difference is that we always specify the version in the content of the document page, even if it is the latest version.
The latest version of Vertopal API: v1
https://api.vertopal.com/example/endpoint refers to https://api.vertopal.com/v1/example/endpoint
In the following cases, we provide a new version:
- removing or changing an endpoint path.
- changing the HTTP method of the endpoint.
- changing the structure of the response or the request.
- removing or changing a key in response or request structure.
- removing or changing the supported type for the key.
- adding a new required key or making a change of the optional key to required.
- adding new validation rule for keys.
- removing or changing a value from predefined values.
- changing authentication or process flow.
- and similar things.
In the following cases, we do not provide a new version:
- improving performance or increasing security.
- fixing minor or major bugs.
- adding an endpoint.
- adding an optional key in the request structure.
- adding a key in the response structure.
- adding another supported type for the key.
- adding a value to predefined values.
- and similar things.
When a new version is released, the previous version will continue to be active and receive all updates for at least 2 years after the newer version is released. If any tips are needed to migrate from one version to a newer one, we will provide them.