Why version the API?
- Every time we release then we run the risk of breaking someone's client
- By mandating API versioning then we can deploy multiple version alongside each other which we deprecate old versions of the API
Where do you put the version?
- The version could be in the URL, in a custom header, or in the "Accept" header
- Accept header versions the response, not the request
- URL is user friendly, but departs from hypermedia as state
- Custom header seems optimal
What does the version consist of?
- CREST version X
- Resource implementation version Y
- Separated by semi-colon
What are we versioning?
- Number bumps when there is a non-backwards compatible change
- Separate version for CREST (0 if CREST is not used), and the resource implementation
How to query which versions are present?
- Check documentation (Swagger?)
- Each request will return the specific version of the API that dealt with the request
How do we handle the version?
- If the version in the header is deployed on the server then server the result as normal
- If the version in the header is not deployed then provide an error message
- If the version is not in the header then:
- If mode is "allow" then just use the latest resource version available
- If mode is "warn" then use the latest and provide a "_warning" attribute in the response
- If mode is "deny" then provide an error message without handling
- Convert header to context
- Have the router deal with the version and provide error/warnings as necessary
- Ensure that the version can be expressed logically in CREST
- Matt to create JIRA issues for CREST
- Jonathan to remove version from authn URL, implement version header