[openstreetmap/openstreetmap-website] API stability policy (Issue #3837)

[Andy Allan]

> how / how soon breaking changes would be announced if at some point deemed necessary.

The last major revision to the API was over a decade ago, so for the next major breaking change it's not possible to call upon any recent precedent. Any policy or discussion veers rapidly into the hypothetical.

Previously breaking changes were announced a few months in advance, but they were "stop the world" changes, where the API was switched off for a period (up to several days) and switched back on again with the new version. My personal opinion is that this "stop the world" approach is no longer practicable given the size of the project, and instead we are more likely to see an overlap period, with multiple versions of the API available and a months-long deprecation timeline. However, this is not a universally held opinion among the development community, and it also depends on what sort of changes are proposed. Again, this all becomes hypothetical quite quickly.

In the meantime, we've made several minor breaking changes to the API, for example removing the `/changes` endpoint, usually by contacting the individual projects using the affected API until the remaining traffic is minimal. I can see this approach continuing for other minor breaking changes, unless major API changes become routine enough that the minor changes can be combined into that process.

I realise this is a bit vague but I hope it is still useful. In short, for breaking changes and deprecation periods, the words "rarely" and "months not weeks" would generally apply.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/3837#issuecomment-1346180916
You are receiving this because you are subscribed to this thread.

Message ID: <openstreetmap/openstreetmap-website/issues/3837/1346180916 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20221212/55f61d5b/attachment.htm>