[ADP-41] API Versioning

Guidance

• MUST implement version control for API endpoints that are above the external audience (i.e., audience≥PARTNET_EXTERNAL).

  INFO

  For information on API audiences, please refer to ADP-752.

• SHOULD choose and document a common version control strategy.
  • DRAFT We prefer using URI versioning as it is very clear in the URL; however, content negotiation through versioning may offer more feasibility.
• MUST use semantic versioning.
• SHOULD avoid breaking changes whenever possible.
• SHOULD NOT remove object properties unless you are prepared to increment the major version number.
• SHOULD consider supporting both new and old versions of the API for endpoints above the external audience (i.e., audience≥PARTNET_EXTERNAL).

Design Thinking

There are various mechanisms for API version control, each with its use cases and advantages:

1. URL Versioning
   • Domain Versioning: This method involves changing the domain name to reflect the version. For example, api.v1.example.com and api.v2.example.com. This method is useful for major version changes but may complicate DNS management and increase maintenance costs.
   • URI Versioning: This is a common method where the version is included in the path. For example, example.com/api/v1/resource. It is intuitive and easy to implement and understand.
2. Query Parameter Versioning
   • This method involves adding a version parameter in the query string. For example, example.com/api/resource?version=1. This is useful for optional version control and testing new versions without changing the base URL.
3. Header-based Versioning
   • Version information is included in the HTTP headers. For example, adding a custom header API-Version: 1. This method keeps the URL clean and flexible but may be less visible to users and developers.
4. Resource-based (Content-Type, MIME) Versioning
   • The version is specified in the Content-Type header. For example, Content-Type: application/vnd.example.v1+json. This method is useful for APIs that need to support multiple content types and versions simultaneously.

Common Values for Version Control

1. Semantic Versioning: Using major and minor version numbers, such as v1 or v1.1.

2. Date-based: Using dates to represent versions, such as 2024-07-08.

   TIP

   Date-based versioning still follows the principles of semantic versioning. The date represents the release date of the major version, not the modification date of the API. If the API release does not include breaking changes to its schema, the date version value should remain unchanged.

Please note that version control strategies may change as the API development matures.

References

• For articles related to why API versioning is difficult, please refer to:
  • https://apisyouwonthate.com/blog/api-versioning-has-no-right-way/
  • https://stripe.com/blog/api-versioning
  • https://blog.treblle.com/api-versioning-all-you-need-to-know/
  • https://www.postman.com/api-platform/api-versioning/