4.7. 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

4.7.1. Version names

  • Semantic versioning

  • Django versioning

  • alpha

  • beta

  • rc (release candidate)

  • gm (golden master)

4.7.2. 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.

4.7.3. Django Versioning

  • 2.0 (experimental)

  • 2.1 (stabilization

  • 2.2 (long term support)

  • 3.0 (experimental)

  • 3.1 (stabilization

  • 3.2 (long term support)

  • 4.0 (experimental)

  • 4.1 (stabilization

  • 4.2 (long term support)

4.7.4. API Policy

  • Deprecation Policy

  • Phasing (sunset date)

  • Darkening

  • PendingDeprecation

  • Deprecated

>>> import warnings
>>>
>>> def add(a,b):
...     a + b
>>>
>>> def sumuj(a,b):
...     warnings.warn('Użyj funkcji add()', PendingDeprecationWarning)
...     return add(1,2)
>>>
>>>
>>> sumuj(1, 2)
>>> add(1,2)

4.7.5. Controlling

4.7.6. How to version API?

Table 4.16. How to version API?

Example

Description

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

API version as a part of URL

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

Version as a parameter to URL

https://api-v2.example.com

Subdomain

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

Subdomain+URL

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

4.7.7. Use Case - 0x01

$ 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"}

4.7.8. Use Case - 0x02

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