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)
** See https://gitlab.wikimedia.org/repos/cloud/toolforge/builds-api/-/merge_requests/79
* Wrap all API responses in `{"messages": {"info": [], "warning": [], "error": []}}` as a common vector for api deprecation information for the user
** see https://gitlab.wikimedia.org/repos/cloud/toolforge/builds-api/-/merge_requests/81
* 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:
* Document the processExpose 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
* 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 incompatibilitiesas 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
== If needed, implement a grafana dashboard with the amount of calls to each method (so we know if there's users using each endpoint).