This repository was archived by the owner on Jun 11, 2024. It is now read-only.
This repository was archived by the owner on Jun 11, 2024. It is now read-only.
Versioning #2
Description
Implement API versioning.
Inspiration:
https://aandeslagmetdeomgevingswet.nl/publish/pages/143597/api-strategie_-_12_maart_2018.pdf
Think about:
- API is a contract that cannot be changed
- Use semantic versioning (major: breaking changes (rename or delete), minor: additions of fields and resources, patch: bugfixes)
- Version number for the complete API (instead of per resource)
- Major version number in the url: e.g. https://api.data.amsterdam.nl/v1/... (instead of query parameter or in Accept and Content-Type headers)
- Minor version number and patch number in API documentation (Swagger, HAL JSON, ...)
- Version state (if not final) in version name. e.g https://api.data.amsterdam.nl/v2beta/...
- Allow for deprecation of versions (version info in API documentation)