Version Parameters for Web Services
When designing a service API, there are lots of things you can do right, and plenty of pitfalls. Most of both of these are completely specific to the situation you are designing for but I have one tip that has helped me out in a number of scenarios: Include a version parameter with every method call.
This is invaluable, not just in development where you can increment when you change the API (which could be quite often!) but also in production. For example if you want to extend or alter an existing service, you can identify which version of the API the client thinks it is accessing and behave accordingly – either letting them know there’s a new version, or preserving previous behaviours. Its never ideal to change the API of an existing service but sometimes it makes more sense to do so, especially if its just to include an additional parameter or something else quite minor, but which does cause an API change.
When you publish your shiny new service which does everything you need (including the hoovering), it might seem a bit redundant to require a field which is always set to the string “1.0” … but in 18 months time, you’ll be patting yourself on the back.
Interesting post, but more detail would be welcome:
– is it a good idea to put version nr. in url, so that new versions of the same webservice can be immediately located?
– is using the classic major.minor.revision versioning scheme a good idea or is it overkill?
– shall both clients and servers validate the version of the other party?
@Gaetano My preference is put version in the URL. This gives you some flexibility on whether to completely branch off and have a new set of API code, or to simply pass the version in as a parameter.
The only scary part about this is that there are now multiple versions of the same API that need to be tested.
Gaetano: I quite like having the version in the URL but that depends a lot on what kind of service you designed as to what makes most sense. I like major.minor as a naming scheme but it is probably overkill as really APIs shouldn’t be changing a lot.
Chris: Whether you support multiple versions of the API is an application decision – knowing which version the user expected means you can identify who is using which version, and either support them or perhaps notify them to upgrade – or run one testing version and one live. It just adds in the extra possibilities for later, how you use those will depend on your requirements.
This the last entry in a mini series on points to consider when designing and building web services. So far there have been posts on error feedback for web services, auth mechanisms for web services, saving state in web services and using version paramet
Over the summer months I wrote a series of posts about designing APIs in general, and web services in particular. This included posts on status codes for web services, error feedback for web services, auth mechanisms for web services, saving state in web