search

WordPress / openverse

Openverse is a search engine for openly-licensed media. This monorepo includes all application code.
https://openverse.org
MIT License
243 stars 194 forks source link

RFC Request: API Versioning #662

Open sarayourfriend opened 1 year ago

sarayourfriend commented 1 year ago

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

dhruvkb commented 1 year ago

I think your request is very comprehensive and covers almost all the questions I can think of about the versioning of our endpoints.

Additionally I would want to know

  1. How long do we support an old version once a new version has come out?
  2. How do we deprecate and eventually discontinue EOL versions?

I do want to recommend the author of the RFC to read GitHub's versioning policy as I believe it is a very solid role-model to use when building our own. We don't need to copy 100% of it, but it's a very good launching point. It lists a number of changes that would be considered breaking and would be a version bump, and a number of backwards compatible changes that will not bump the version.

We should consider posting something like GitHub's policy on our ReDoc site once we've finalised the RFC.

zackkrida commented 1 month ago

@dhruvkb I really like the suggestion to take inspiration from Github's versioning policy. Another API I recently came across with excellent versioning policies is Klaviyo.

Interestingly, I also noticed that they use a "revision" header for their versioning rather than a path-based versioning. I've observed APIs add the version in the "Accept" header but never a custom header before.

I wanted to revive the conversation here in light of the idea to remove the watermark endpoint in #4835

sarayourfriend commented 1 month ago

I wanted to copy over something I wrote in the watermark endpoint discussion, because it would be good to consider when discussing this policy:

Whatever versioning policy and strategy we decide, we should make sure it doesn't tie our hands into operating endpoints that have the quality of this one in perpetuity: underused and potentially high-risk. We would need to have some way for us to give a notice of breaking changes, even for well-used endpoints, including removal. Which would only be available to registered API users, by nature of needing a communication channel. We could assume unregistered API users are not planning long-term, stable integrations.

@zackkrida perhaps we can plan to discuss the versioning policy in person during the core maintainer meetup? The goal could be just to decide on the outline of a policy and the process around that policy. Because this issue also needs to consider the method of implementing versioned changes to the API, we would then have a separate IP that explores methods for handling versioning in the API code itself. I think it would be helpful to cut the scope of this issue to "implement the technical plumbing for {this policy we decided to follow}" rather than also being about deciding the policy. Both together is daunting.