3.1. HTTP API Versioning

  • Always version API

  • Have stable API!

  • Do not use plural in resources

  • Use HTTP Statuses

  • Use HTTP Methods

Latest is the greatest! -- Old programmers joke

3.1.1. Semantic Versioning

  • https://semver.org/

  • 2.0.0

  • MAJOR.MINOR.PATCH

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards compatible manner, and

  • PATCH version when you make backwards compatible bug fixes.

  • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

3.1.2. API Policy

  • Deprecation Policy

  • Phasing (sunset date)

  • Darkening

  • PendingDeprecation

  • Deprecated

>>> import warnings
>>>
>>>
>>> def addition(a,b):
...     warnings.warn('Use add() function instead', PendingDeprecationWarning)
...     return add(1,2)
>>>
>>>
>>> def add(a,b):
...     a + b
>>>
>>>
>>> addition(1, 2)
>>> add(1, 2)

3.1.3. Controlling

3.1.4. How to version API?

  • https://example.com/user/10?api=v2 - Version as a parameter to URL"

  • https://example.com/api/v2/user/10 - API version as a part of URL"

  • https://api.example.com/v2/ - Subdomain+URL"

  • https://api-v2.example.com - Subdomain"

  • X-API-VERSION: 2 - Version as a custom header with X-... prefix"

  • Accept: application/vnd.api.v2 - API version as a custom vendor prefix for Accept header"

  • Accept: application/vnd.api.v2;q=0.9,application/vnd.api.v1;q=0.8 - API version negotiation with weights using Accept header

Table 3.14. How to version API?

Example

Description

https://example.com/user/10?api=v2

Version as a parameter to URL

https://example.com/api/v2/user/10

API version as a part of URL

https://api.example.com/v2/

Subdomain+URL

https://api-v2.example.com

Subdomain

X-API-VERSION: 2

Version as a custom header with X-... prefix

Accept: application/vnd.api.v2

API version as a custom vendor prefix for Accept header

Accept: application/vnd.api.v2;q=0.9,application/vnd.api.v1;q=0.8

API version negotiation with weights using Accept header

3.1.5. Use Case - 1

$ curl http://localhost:8000/user/1 -H 'X-API-VERSION: 1.0'
{"name": "Mark Watney"}

$ curl http://localhost:8000/user/1 -H 'X-API-VERSION: 2.0'
{"firstname": "Mark", "lastname": "Watney"}

3.1.6. Use Case - 2

https://jira.atlassian.com/rest/api/1/issue/JRA-9
https://jira.atlassian.com/rest/api/2/issue/JRA-9
https://jira.atlassian.com/rest/api/latest/issue/JRA-9