API Version in resource URLs

First post!

Excited to read about the new API; JSON responses will make much life
easier.

I’m also pleased to see the API returning URIs for resources instead of
just identifiers. I’m a big fan of this style of REST API as it reduces the
amount of knowledge the client needs of the API. In particular, if you have
some kind of offline representation of a resource (a local persistent
model), they can just keep a reference to their paths - great.

However, I was disappointed to see that you’ve gone down the route of
embedding the API version in the URI. What you’ve essentially done is made
migrating to a new API version harder than it needs to be.

Conceptually, I don’t believe a resource should need to change it’s URI.
Project X should ideally always exist at /api/projects/x. The API version
should dictate what exactly gets returned from that resource (it could be
a different schema for example). However, by embedding the API version in
the URL, you’ve essentially committed to changing the resource URIs when
the API version number changes. For me, the client, this means having to go
through and update all of the paths in my offline persistent store, rather
than simply requesting the new version via content negotiation.

Of course, any version change and any resulting schema change would mean
I’d have to update my app, but it would be nice if my app could continue to
fetch it’s remote representation from the same place and simply request
what version it expects to handle (assuming a new version didn’t
automatically remove support for the previous version).

There’s a great article here that explains this in more detail:
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

I’d be interested in hearing the reason for going down this route and if it
there is any chance of this being reconsidered so close to launch.

Thanks!

We’ve been talking over this internally and are considering dropping the
/v2 from the url. Api v2 is accessed over the api subdomain so there’s no
risk of confusion with api v1. The way things are going, if there’s ever a
third version of the API, I imagine it’s probably not going to be a set of
http routes over the api subdomain but something involving web sockets.

I’m not keen on custom mime types for public apis though. I expect most
developers would just use application/json and we’d either have to tie
their app to the first version of api v2 deployed or always to the latest
version - which might break apps. I wouldn’t want to enforce the use of a
custom media type - we want to keep the barrier to entry to using the api
as low as possible.

I’m leaning towards trying to maintain backwards compatibility rather than
having to maintain multiple point releases which again I think makes life
easy for developers (though not for us!). Anyway time grows short for
making this sort of breaking change to API v2 so if anyone else has any
suggestions like this - let’s hear them!

GraemeOn 7 March 2012 20:02, Luke Redpath ljredpath@gmail.com wrote:

On Wednesday, March 7, 2012 4:24:34 PM UTC, Graeme Boyd wrote:

A key part of our implementation is that URIs are opaque identifiers.
The fact that they contain a version string is more important to the
server than the client. The sort of versioning scheme the article you link
to proposes makes it more difficult to use generic API clients like the
Google OAuth 2.0 Sandbox.

Why is this important? I’d never even heard of Google OAuth 2.0 sandbox
before today. Isn’t this just leaking implementation details? I don’t see
how this makes it harder for people to use; we’re just talking about an
HTTP header, right?

Media-type versioning is a good solution where you expect old versions of
an API to exist forever, you expect clients to use multiple versions at the
same time or to slowly transition to a new version. I don’t think it’s
necessary where a new version will break backwards compatibility and old
versions are eventually retired.

I would expect in the event of a new version of an API being released,
that the previous version would be deprecated and stick around for a while
and not just go away entirely.

Naturally, in order to use a new version of the API, I’d have to update my
app, tell it to use the new version and make any code changes that
requires. But I shouldn’t have to update all of the existing data in my app

  • all of my local data that knows where it lives on the server should
    continue to know where it lives - there is no good reason for a resource to
    change it’s URI that I can think of. So really, you’re creating more work
    for developers.

I’m not requesting this out of some quest for technical purity, it just
seems crazy to me that we are going to use identifiers for records that
could change when the API changes.

Nic’s suggestion seems like a good compromise; why not omit the /v2 part
in the returned URIs entirely?


You received this message because you are subscribed to the Google Groups
“FreeAgent API” group.
To view this discussion on the web visit
https://groups.google.com/d/msg/freeagent_api/-/ReBPciiMT44J.

To post to this group, send email to freeagent_api@googlegroups.com.
To unsubscribe from this group, send email to
freeagent_api+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/freeagent_api?hl=en.

Graeme Boyd
Senior Software Engineer
FreeAgent Central Ltd
40 Torphichen Street, Edinburgh EH3 8JB
Registered in Scotland SC316774

Hi Luke,

Thank you for linking to the article. There are many differing opinions on
how to structure an API and our primary influence has been looking at how
other companies have deployed APIs as we want our API to be as familiar and
easy to adopt as possible.

A key part of our implementation is that URIs are opaque identifiers. The
fact that they contain a version string is more important to the server
than the client. The sort of versioning scheme the article you link to
proposes makes it more difficult to use generic API clients like the Google
OAuth 2.0 Sandbox.

Media-type versioning is a good solution where you expect old versions of
an API to exist forever, you expect clients to use multiple versions at the
same time or to slowly transition to a new version. I don’t think it’s
necessary where a new version will break backwards compatibility and old
versions are eventually retired.

Thanks for suggesting it though!

Kind regards,

GraemeOn 7 March 2012 12:18, Luke Redpath ljredpath@gmail.com wrote:

First post!

Excited to read about the new API; JSON responses will make much life
easier.

I’m also pleased to see the API returning URIs for resources instead of
just identifiers. I’m a big fan of this style of REST API as it reduces the
amount of knowledge the client needs of the API. In particular, if you have
some kind of offline representation of a resource (a local persistent
model), they can just keep a reference to their paths - great.

However, I was disappointed to see that you’ve gone down the route of
embedding the API version in the URI. What you’ve essentially done is made
migrating to a new API version harder than it needs to be.

Conceptually, I don’t believe a resource should need to change it’s URI.
Project X should ideally always exist at /api/projects/x. The API version
should dictate what exactly gets returned from that resource (it could be
a different schema for example). However, by embedding the API version in
the URL, you’ve essentially committed to changing the resource URIs when
the API version number changes. For me, the client, this means having to go
through and update all of the paths in my offline persistent store, rather
than simply requesting the new version via content negotiation.

Of course, any version change and any resulting schema change would mean
I’d have to update my app, but it would be nice if my app could continue to
fetch it’s remote representation from the same place and simply request
what version it expects to handle (assuming a new version didn’t
automatically remove support for the previous version).

There’s a great article here that explains this in more detail:
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

I’d be interested in hearing the reason for going down this route and if
it there is any chance of this being reconsidered so close to launch.

Thanks!


You received this message because you are subscribed to the Google Groups
“FreeAgent API” group.
To view this discussion on the web visit
https://groups.google.com/d/msg/freeagent_api/-/qbWOgJvTLioJ.
To post to this group, send email to freeagent_api@googlegroups.com.
To unsubscribe from this group, send email to
freeagent_api+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/freeagent_api?hl=en.

Graeme Boyd
Senior Software Engineer
FreeAgent Central Ltd
40 Torphichen Street, Edinburgh EH3 8JB
Registered in Scotland SC316774

A key part of our implementation is that URIs are opaque identifiers. The
fact that they contain a version string is more important to the server
than the client. The sort of versioning scheme the article you link to
proposes makes it more difficult to use generic API clients like the Google
OAuth 2.0 Sandbox.

Why is this important? I’d never even heard of Google OAuth 2.0 sandbox
before today. Isn’t this just leaking implementation details? I don’t see
how this makes it harder for people to use; we’re just talking about an
HTTP header, right?

Media-type versioning is a good solution where you expect old versions of
an API to exist forever, you expect clients to use multiple versions at the
same time or to slowly transition to a new version. I don’t think it’s
necessary where a new version will break backwards compatibility and old
versions are eventually retired.

I would expect in the event of a new version of an API being released, that
the previous version would be deprecated and stick around for a while and
not just go away entirely.

Naturally, in order to use a new version of the API, I’d have to update my
app, tell it to use the new version and make any code changes that
requires. But I shouldn’t have to update all of the existing data in my app

  • all of my local data that knows where it lives on the server should
    continue to know where it lives - there is no good reason for a resource to
    change it’s URI that I can think of. So really, you’re creating more work
    for developers.

I’m not requesting this out of some quest for technical purity, it just
seems crazy to me that we are going to use identifiers for records that
could change when the API changes.

Nic’s suggestion seems like a good compromise; why not omit the /v2 part in
the returned URIs entirely?

Sorry, I’m kinda flat out with work at the moment, but:

I’m also pleased to see the API returning URIs for resources instead of just
identifiers. I’m a big fan of this style of REST API as it reduces the
amount of knowledge the client needs of the API. In particular, if you have
some kind of offline representation of a resource (a local persistent
model), they can just keep a reference to their paths - great.

However, I was disappointed to see that you’ve gone down the route of
embedding the API version in the URI. What you’ve essentially done is made
migrating to a new API version harder than it needs to be.

I’m curious about this bit:

"I’m a big fan of this style of REST API as it reduces the

amount of knowledge the client needs of the API"

Is that a bit of a straw man (in a astronauts suit)? Does anyone
actually write a client for an API which is not bound fairly tightly
to a specific version of the API contract? I know of one architect who
was trying to design a system which was highly discoverable, because
he could and because he thought “then everyone can just query the
interfaces and find out what to call”, but I’m not sure it ever got
implemented.

As I said on twitter, would the solution (or workaround) be:

change the URI’s in the ID’s to be /contacts/2 (not /v2/contacts/2),
and the consumer can use the version prefix (/v2) to get it - but the
ID URI for contact #2 stays as /contact/2. This works around the “I
had v1 now I have v2 and I’ve changed my client” thing, and the server
can work out which version I want (or error me).

It does ignore the “v2 exists, v1 has gone away” issue, but I dont see
a way around a whole version going away. Aside from not doing it.

Sorry, a bit disjointed - got a fair bit on at the moment :slight_smile:

N

Nic Wise
t. +44 7788 592 806 | @fastchicken | http://www.linkedin.com/in/nicwise
b. http://www.fastchicken.co.nz/

Nearest Bus: find when the next bus is coming to your stop. http://goo.gl/Vcz1p
mobileAgent (for FreeAgent): get your accounts in your pocket.
http://goo.gl/IuBU
Trip Wallet: Keep track of your budget on the go: http://goo.gl/ePhKa
London Bike App: Find the nearest Boris Bike, and get riding! http://goo.gl/Icp2

We’ve been talking over this internally and are considering dropping the
/v2 from the url. Api v2 is accessed over the api subdomain so there’s no
risk of confusion with api v1. The way things are going, if there’s ever a
third version of the API, I imagine it’s probably not going to be a set of
http routes over the api subdomain but something involving web sockets.

Great news!

I’m not keen on custom mime types for public apis though. I expect most
developers would just use application/json and we’d either have to tie
their app to the first version of api v2 deployed or always to the latest
version - which might break apps. I wouldn’t want to enforce the use of a
custom media type - we want to keep the barrier to entry to using the api
as low as possible.

FWIW, neither am I, at least not in this context. I think application/json
is just fine.