852233 - Add a version to the API

Status: RESOLVED FIXED

(Marketplace Graveyard :: API, defect, P1)

Description

[Matt Basta [:basta]]

The API needs a version in the URL so we can safely deprecate features without pulling out what's left of our hair.

Comment 1

[Alexis Metaireau (:alexis)]

Just a small comment to point out that it could be nice to not have this in the URL, but as an extra information we put in the Accept header for instance. (let's say "Accept: application/json; version=1").

Maybe that would be more REST-ish than having different URLs pointing to the same resource?

I genuinely don't know if the header approach is better or worse and don't have strong feelings yet about that; Maybe some folks have already thought about that?

Comment 2

[Matt Basta [:basta]]

The downside to a header is that it's a fupping pain in the neck to use outside of code. cURL? LOL NAHP. wget? WGNOT.

The second issue is that you're recycling paths. With versioned URLs, you can just create a second django app and be done with it. With unversioned URLs, you have no such luxury, and you'll either write strange and exotic middleware or you'll end up with decorators or switches on all of your tastypie resources. Deprecated but active API versions are going to do to your views/resources what Marketplace did to AMO's codebase.

Third, the biggest thing consuming this is going to be AJAX, and nobody (not even edna) wants to have to use $.ajax() when there's $.get and $.post.

If this were a purely one-off B2B thing (i.e.: we were going to make Bango use it or something), I'd say let's go for it. But this is something even our successors' successors are going to be using, so let's do them a kindness and slap some love on the URL.

Comment 3

[Alexis Metaireau (:alexis)]

It's probably *simpler* for the clients to have the version in the URL. However that's possible to handle it with either cULR or wget, and I do think that reverse proxies are able to do routing depending what's in the header and not only on what's in the URL (for instance HAproxy knows how to do that, and that's probably not the only one).

However, by reading more about this particular question (http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown), it seems it can be harder to handle diverging evolutions of an API (for instance if the resources don't exist anymore / new ones are added).

At the end, it all boils down to what do we want to offer; and I guess having an API that's easy to use is probably what we want to offer, even if the headers approach is more HTTP-like (practicality beats purity).

Comment 4

[Andy McKay]

I'd be fine with putting it in the URL.

I'd hate to have to update docs, links and the likes every time the API changes, which should be very, very infrequent. Could we have /api/latest/ always going to the latest version (good for documentation internal use etc) and users explicitly know that the URLs might change.

If we are changing all existing URLs, now is a fine time to do it, but let's put in redirects and let the very few existing users know about it.

Comment 5

[Matt Basta [:basta]]

(In reply to Andy McKay [:andym] from comment #4)
> I'd hate to have to update docs, links and the likes every time the API
> changes, which should be very, very infrequent. Could we have /api/latest/
> always going to the latest version (good for documentation internal use etc)
> and users explicitly know that the URLs might change.

This can be a bit of a pitfall, I'd imagine. Even if users know that the URLs might change, that doesn't save them from the output suddenly changing and breaking their implementation as soon as we switch on a new version of the API.

A common practice is to version the docs of the API with the API itself. Consider the following:

https://dev.twitter.com/docs/api/1.0
http://www.yelp.com/developers/documentation

https://developers.google.com/youtube/v3/
vs
https://developers.google.com/youtube/2.0/

http://dev.bitly.com/data_apis.html (though they don't keep old API docs)


> If we are changing all existing URLs, now is a fine time to do it, but let's
> put in redirects and let the very few existing users know about it.

Agreed. I'd even be inclined to move the "future" version of the API to a subdomain and deprecate the current /api routes:

https://api.marketplace.firefox.com/v1/...

That way, we're not stomping on our existing users until we phase out the old API(s) and the new APIs will be able to stretch their legs going forward. What do you think about that?

Going forward we should probably think about an implementation similar to what Foursquare has:

https://developer.foursquare.com/overview/versioning

Basically the client passes the date that they were last updated on, and the API tells them if they are potentially using deprecated functionality.

Comment 6

[Andy McKay]

(In reply to Matt Basta [:basta] from comment #5)
> (In reply to Andy McKay [:andym] from comment #4)
> https://developers.google.com/youtube/2.0/

Its a very good point that the documentation should be versioned correctly. Part of the reason I'd like to fix our current (zamboni docs - version 0.8 what).

> Agreed. I'd even be inclined to move the "future" version of the API to a
> subdomain and deprecate the current /api routes:
> 
> https://api.marketplace.firefox.com/v1/...

So /api/v1/ still works for me.

> That way, we're not stomping on our existing users until we phase out the
> old API(s) and the new APIs will be able to stretch their legs going
> forward. What do you think about that?

Yeah, /api/v1/ would work.

> Going forward we should probably think about an implementation similar to
> what Foursquare has:
> 
> https://developer.foursquare.com/overview/versioning

Yeah how we'll deprecate and send other messages to our clients is an interesting point. I note that four square also says:

"In the future, the default will be to use the most recent API"

Comment 7

[Wil Clouser [:clouserw]]

is there a reason you're wanting /v1/ instead of /1/ like our current API?

Comment 8

[Andy McKay]

No /1/ is fine.

Comment 9

[Andy McKay]

https://github.com/mozilla/zamboni/commit/81a095

I used v1 because when I look at the URL its more obvious its a version and not a pk. Boring docs search and replace commit to come in a moment.