I have been conducting some research into RESTful web service design and I've reached what I think is a key decision point so I thought I'd offer it up to the community to get some advice.
In keeping with the principles of a RESTful architecture I want to present a discoverable API, so I will be supporting the various HTTP verbs as fully as possible. My difficulty comes with the choice of representation of those resources. You see, it would be easy for me to come up with my own API that covers how search results are to be presented and how links to other resources are provided, but this would be unique to my application.
I've read about the Atom Publishing Protocol (RFC 5023), and how OData promotes its use, but it seems to add an extra level of abstraction over what is (currently) a rather simple API.
So my question is, when should a developer select AtomPub as their choice of representation – if at all? And if not, what is the current recommended approach?
Best Answer
After doing a fair amount of research into this, here are my findings:
There seem to be 3 primary formats and approaches: AtomPub, OData and HAL. I've summarised the research for each below.
AtomPub
OData
Pro: Builds on AtomPub
Pro: Works with XML and JSON
Pro: Has good Java support through the odata4j project
Pro: Provides a good URI query structure
Con: Introduces a complete framework (essentially replaces Dropwizard)
Con: Very complex to work with, particularly the entity data model (EDM)
Con: Difficult to find a good JavaScript client library without relying on Windows-only tools for EDM
HAL
So when should I use AtomPub?
From the above one should choose AtomPub if you're happy with the additional complexity and want to use standard libraries for your clients. This would probably be the case if you're running a large document repository.
I've put more detail (which is out of scope for this question) into a recent blog article that might be of help to others.