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

2.7.1. Version names¶

Semantic versioning
Django versioning
alpha
beta
rc (release candidate)
gm (golden master)

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

2.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)

2.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)

2.7.5. Controlling¶

OAuth apps
Basic Auth
JWT (bearer)
Rate limiting (throttling)
https://api.github.com/users/astromatt/repos

2.7.6. How to version API?¶

Table 2.13. 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

2.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"}

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