A co-worker put me on to the chapter in "Architecting Composite Applications and Services with TIBCO", which is so old it talks about WSDL. Thankfully, the things it has to say about versioning is above and beyond any specific technology. To look at the basics, it's usually easier to pattern match on the URL. So /API/foo1 and /API/foo2 tend to be easier to work with than getting the headers in the request, depending on your loadbalancers. You could do /API/v1/foo, /API/v1/bar , but then when any call has a breaking change do all calls upgrade to v2? Or do you have per-call URI paths? I prefer to version at the end of the endpoint name and not set the version inside the string, although people like Twilio think differently and probably have extremely good reasons (their version string is the date the API was released) Something that I've found to be powerful is including the client version in the request headers. That way, a bug in the client can be dealt with by the interface or provider, rather than a forced client update.