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

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