Proposal: Add versioning to our API

This is an offshoot of the epic thread that lays out the larger plan for the API. I’m looking to break off a bite-size chunk that we can scope discussion to and therefore get to a consensus and a plan of action on.

Current state of the world

Right now we have a number of unofficial API endpoints. We know that a number of people and apps rely on them: the OFN front end and Zapier, to name two. There are also potentially other people/apps using them that we don’t know about.

These unofficial endpoints are not something we want to support long term.

Desired state of the world

In the future, we’d like to have an officially supported and well-documented API. We know that we’ll need to make changes to that API over time as OFN grows and changes, so we’ll need a way to version that API. A common way to do this, and one I’ve used in the past, is to embed the version number in the URL, e.g. /api/v1/products.json. Optionally, there can be a non-versioned URL that redirects to (or returns) the latest version, e.g. /api/products.json would redirect to or return the same as /api/v2/products.json if v2 is the latest API version.

Note: This proposal is entirely @Matt-Yorkley’s idea :wink:

Since we want to introduce versioning anyway, let’s start now. The current endpoints are a kind of 0.1 version of the API and not intended for public consumption. So let’s call them that, by moving them all under a namespace: 0.1, private, internal, and legacy are all good candidates for the name.

This PR (also initiated by Matt) does exactly that, and it has a green build. It implements a simple redirect from /api/* to /api/legacy/* so that existing integrations like Zapier won’t break. legacy could easily be changed to 0.1 or another option.

Requirements for implementing said proposal
Since this does commit us (though not irreversibly) to a strategic direction, we need buy-in from at the very least the core-dev team that this is a technically sound idea and something we can all work with.

It also affects the larger OFN community since it will bring changes to the way the API and Zapier work (though as I said, it makes the transition as seamless as possible). So putting this discussion somewhere other than Slack or Github is another requirement.

Lastly, we’d need to test to make sure that the proposed changes won’t break any major existing apps that rely on the unofficial endpoints, like Zapier. If you’re reading this and have built something that uses them, please reply with details :smiley:

A poll, for fun

I don’t want to commit to using the most popular option (we will not name the current API BoatyMcBoatfaceVersion1.boat) but here is a poll to see if there’s a clear people’s choice candidate:

What should we call our current API version?
  • 0.1
  • legacy
  • internal
  • private

0 voters

1 Like