Problem

We currently do not have documentation nor established patterns and infrastructure for deploying a v2 API version prefix. We also do not currently have a well documented set of changes that we are willing to accept into any given API version prefix which has led to a number of discussions in different issues about what we can and cannot change at the moment. Things like changing API response shapes, removing API endpoints, changing their inputs, and so forth.

Description

I want to request that an RFC is written the covers the following:

1. What is the purpose of a versioned API for the Openverse project and what guarantees are we prepared to make for any given version prefix?
2. How will we document breaking changes to version prefixes when they're needed (sometimes they're unavoidable) and changes between version prefixes?
3. How would we go about actually implementing a new v2 version of one of our existing endpoints? Would we try to make the endpoints able to evolve over time and share as much code as possible? Would we copy/paste the existing code and "lock" the old version, so to speak? I've personally seen both done and both have their trade-offs. It'd be great to have prior art to point to here as I'm sure it's a problem that's been solved many times in many different ways.
4. Should we have an unstable version prefix (e.g., /beta/images/?q=birds)?
5. Should the v1 prefix be redirected to this unstable prefix and ultimately v1 skipped until we're ready to commit to a stable API, perhaps after adding one more media type and ironing out our data normalisation issues?
6. How would we decide when an unstable version would get promoted to have a stable version prefix?
7. Are our APIs semantically versioned? For example, would we ever have a vX.Y.Z prefix?

Additional context

@dhruvkb @krysal @obulat do y'all have any additional things you think should be covered by an API versioning RFC?

Implementation

• 🙋 I would be interested in implementing this feature.