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.