API RESTful Design question:  Versioning number in the URL? »

We're starting to get some great questions from signups for next week's API design webinar:  "Pragmatic REST - API Design Fu". 

Here's one we'll comment on now and then talk about more next week.

Q: "For API Versioning.  Doesn't seem very RESTful to version a resource.  Can it be avoided by using implementation and specification versions described in the Sun API Cloud Documentation?"

A: Your question is an insightful one. Versioning is an open issue for REST API design in practice.

Clearly, an API will need to change it's behavior over time. As it changes application developers will need to change their code accordingly. So, versioning is inevitable.  

(caveat: Dan Jacobson of Netflix and NPR's API program has great points on what he calls a 'versionless API' in this presentation around slide 202.")

Our point of view here at Apigee is API design approach we call pragmatic REST.

The driving philosophy of our approach is: what's good for the application developer is good for the API. The Sun Cloud approach to versioning is interesting. The upside is it's powerful and will handle cases of inter-dependent API calls well.

The downside is it's complicated and as a developer starts using it, there is a lot to learn. Plus, because the versions are specified in the header, he won't be able to copy & paste it into the browser to learn it.

Our suggestion - even though it clearly violates pure REST theory - is to include the API version in the URL as a single digit number like /v1, /v2, etc. Whatever complexity is involved in making it "work" is on the shoulders of the API team.

More on this topic in our webinar - sign up here and hope to see you there.