Question

I am creating some web services that produce and consume XML. The plan is to use Jersey 1.x on Tomcat 6.x with JAXB.

What I need to find out is; are there any rule of thumbs to follow when creating these services? What are the common practices when doing a PUT or GET? Does the consumer expect a response, status or object returned?

I’ve been reading and looking at examples of all of these scenarios but each author/blogger and how to seem to address these same scenarios differently.

Any suggestions from those who have been doing this a while?

Thanks

Answer 1

A few things everybody seem to agree or disagree on:

1. Invalid requests return an HTTP 400 code. The 500 should only be used for ‘unexpected exceptions’.
2. Though there is no definitive norm, try to use Clean URLs. On top of the benefits mentioned, it makes it easier to set-up reverse proxys if you need any.
3. On HTTP Methods, while there seems to be agreement on GET and DELETE, there is debate on which of PUT or POST does create or update. See this discussion. Finally some proxies or web servers (IIS anyone) do not always handle anything else than GET and POST easily so you have to resort to an additional X-HTTP-Method-Override header to specify your actual method.
4. You should respect the Accept header and return content of the type requested. The text types (XML, JSON, Plain Text and HTML) are the most common but you may not want to support all of these.

The attractiveness of REST is its simplicity; make sure you keep it this way. Being simple, documenting the services is easy and that is the real key, not that your are using POST or PUT.