11436 SSO

RESTful API Design: how many versions?

Brian Mulloy
Jan 20, 2012

I've talked about versioning as one of the most important considerations when designing your pragmatic RESTful API.

So it deserves another mention.

Basic versioning recommendations

  • Never release an API without a version.
  • Make the version mandatory.
  • Specify the version with a 'v' prefix. Move it all the way to the left in the URL so that it has the highest scope (e.g. /v1/dogs).
  • Use a simple ordinal number. Don't use the dot notation like v1.2 because it implies a granularity of versioning that doesn't work well with APIs--it's an interface not an implementation. Stick with v1, v2, and so on.

How many versions should you maintain?

Maintain at least one version back.

For how long should you maintain a version?

Give developers at least one cycle to react before obsoleting a version.

Sometimes that's 6 months; sometimes it's 2 years. It will depend on your developers' platforms. For example, mobile apps take longer to rev than web apps.

Next time we'll look at making requests to our RESTfully designed APIs.


Scaling Microservices