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.