Capitan PHP

This is 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 and saving state in 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.