search

getmovement / deprecated-movement-rails-api

DEPRECATED Rails API for getmovement.org
1 stars 1 forks source link

API versioning [discussion] #2

Open christopherstyles opened 8 years ago

christopherstyles commented 8 years ago

@JoshSmith commented:

With Field the Bern, we made no assumptions and just decided to tread kind of recklessly with regards to versioning.

I'd been reading a lot about how Stripe does their versioning using gates and request/response layers with date headers instead of hardcoded URL versions.

We may not (at first) have many consumers beyond our own few clients. So we should balance decisions here with an eye towards understanding resource constraints and longevity. We may have more than three clients at some point. And we may have more than us consuming the API. We also don't have a ton of time to devote to a complex scheme, though understand similarly that we want to be able to iterate in fast feedback cycles, so a date-based approach can make more sense.

christopherstyles commented 8 years ago

The last few APIs I’ve worked on, we versioned simply (whole version numbers), using a media type in the Accept header. Something along the lines of:

application/vnd.[appname][+json]; version=[.version]

This worked great for us, I’d certainly recommend using a header over hardcoding a version in the url.

Versioning by date and the concept of cascading gates for incompatible changes is definitely an interesting idea, quite compelling. Once concepted and built, it seems like it could work well for promoting fast iteration.

I’d want to be cautious about prematurely optimizing. How Stripe uses gates and compatibility layers has the potential to get complicated quick. I’m unaware of an open source alternative to the kind of custom tooling they describe, so we would either need to build and maintain something similar ourselves (a significant time investment), or figure out a compromise that meets our needs. Also, perhaps the number of backwards-incompatible changes can be mitigated by more design consideration ahead of time?

One potential compromise could be that we version by date in the Accept header without necessarily creating the system of “gates” and “compatibility layers”, but instead just inherit from previous versions, overriding what needs to change?

Something like this would be fairly easy to implement. I’ve always rolled my own middleware and route constraints, but something open source like versionist or api-versions could possibly work too.