Currently we have a v1.yaml file on the openapi/ folder, with all the methods prepended with v1, but that would mean that to bump one method we have to bump all of them by creating a new v2.yaml file.
There has to be a better way to be able to handle single-method non-backwards compatible changes.
We might want to define a version rollout strategy too before opening the APIs to any users (ex. doing some kind of preview-stable-deprecated-removed cycle or similar).
This task is to:
Find a process to add backwards-incompatible changes to the API while having always a backwards-compatible state
- Move all endpoints to they own full path (so we don't have to bump all the endpoints at the same time)
- Wrap all API responses in {"messages": {"info": [], "warning": [], "error": []}} as a common vector for api deprecation information for the user
- When an endpoint is being deprecated, add a warning message to the response (in the {"messages":{"warning": []...}} array) with the notice period and the migration recommendation.
- When the date comes write an error in the {"messages":{"errors": []...}} for that endpoint and fail it.
- After a buffer has passed, remove the old endpoint.
Extra things to implement:
- Expose stats on the endpoint usage (maybe also by user agent).
Document the process
Define a policy on how long each step of that process is going to be, and how we will be notifying the users about the incompatibilities
Where to announce the deprecations:
- as an entry in the Changelog toolforge page
- as a warning message in the endpoint response
- as a note in the openapi spec docs
Timeline:
- First notification of deprecation - day 0
- Second notification - day 30
- Deprecated - day 60