Change Details

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: * 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 == If needed, implement a grafana dashboard with the amount of calls to each method (so we know if there's users using each endpoint).

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 * [x] 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 * [x] 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: * Expose stats on the endpoint usage (maybe also by user agent). == Document the process Done, created wiki page: https://wikitech.wikimedia.org/wiki/Help:Toolforge/API == 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 == If needed, implement a grafana dashboard with the amount of calls to each method (so we know if there's users using each endpoint). Done: each of the components API dashboard will show the calls to deprecated apis too (ex. https://grafana.wmcloud.org/d/kcAb-KUSz/jobs-api?orgId=1)

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 * [x] 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 * [x] 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: * Expose stats on the endpoint usage (maybe also by user agent). == Document the process Done, created wiki page: https://wikitech.wikimedia.org/wiki/Help:Toolforge/API == 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 == If needed, implement a grafana dashboard with the amount of calls to each method (so we know if there's users using each endpoint). Done: each of the components API dashboard will show the calls to deprecated apis too (ex. https://grafana.wmcloud.org/d/kcAb-KUSz/jobs-api?orgId=1)