web services URL best practice

Though SOAP based web services use XML for the messages, the WS standards do not try to automatically map between messages. XML nodes which are missing or added will cause exceptions, and cannot be handled using defaults. I personally believe this is a major flaw in the web services standards and negates one of the major advantages of using XML for the transport. It would also have been practical to reduce the size of the messages (by having sensible defaults), though this seems to be a consideration which nobody uses any more.

However, I do understand that it can be a pro as well, as this strictly defines the message format.
However, this does mean that you have to consider this from day one. You have to assure your interface are pretty stable before publicising your service. It becomes worse as, contrary to an interface in a programming language like java, automatic refactoring is no option, and worse, as there is no “package” in which the service and the clients are combinesd, you cannot force the clients of your service to switch to the new version at a specific moment.

The solution is to consistently include the version number of your service in the URL. In fact I would recommend a URL with the following template


In this template the “package” is the name of your project, module or other grouping for your services. I would recommend using both a subdomain and initial “directory” level for this as this allows you to choose the machine to deploy this package on, migrating to a dedicated machine at any time if necessary or otherwise changing the allocation of service packages and other web related code to computers. The use of the package name as the root in the path makes it easy to assure the services have non-overlapping urls, without the need to worry about properly handling and configuring the virtual domains.

The “vxx” part in the code allows you to have the different versions of your services. You will obviously need to make sure that the interface does not change for each specific version, and I would recommend including this as a test in your continuous integration. However, you will still need to assure that the “old” versions of the service interact properly with the new improved backend, either by stripping deleted data, adding defaults for the newly added stuff, or if no solution can be found, make sure a suitable exception is thrown.

Leave a Reply

Your email address will not be published. Required fields are marked *

question razz sad evil exclaim smile redface biggrin surprised eek confused cool lol mad twisted rolleyes wink idea arrow neutral cry mrgreen