Designing a Wishlist Service: Interface

One thing that has always struck me about web services is how hard they are to invoke from a web browser. SOAP requests are the worst, with the overhead from its envelope, but even simple XML services leave a lot to be desired. Particularly since Internet Explorer, the most popular browser currently in use, doesn't support the E4X extensions to JavaScript. This has led to diverging paths: either a web service is expected to be used in a browser, and is built around POST data and JSON, or it's meant to be called from another server, and is built around an XML protocol.

For the product list service, I wanted both. My main use case is browser-based requests, but I also want to support Flex application (which prefer XML) as well as server-server requests (such as managing a cart). This led me down the path of REST services.

“REST” seems to be applied to any web service that uses XML and isn't SOAP, so before continuing I should state what it means to me:

1. GET is used for retrieval, POST for update. REST purists will now be upset with me, saying “what about PUT and DELETE?!?” My answer: when HTML supports PUT and DELETE as form methods, and every browser allows them, then we can talk about using them. Until that time, practice trumps theory.
2. The URL uniquely and completely identifies the resource and action. Again, REST purists will object to including the action in the URL, but that's a necessity if we can't use PUT and DELETE.
3. The request and response bodies contain only data. Far too many “RESTful” web services are really XML-RPC in disguise, particularly for update operations.
4. HTTP status codes are used to signal success or failure. For any response other than 200 (Success), the response body will contain error information.

The result is a very simple interface. My desire to support both POST/JSON and XML requests introduces a slight wrinkle, one that's resolved front-end code that identifies the content type and converts to and from a JavaBean representation.

One thing that REST doesn't contemplate, however, is security. That's the next post.