Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
1  
There is an interesting discussion about this here: comments.gmane.org/gmane.comp.web.services.rest/16023 –  Gary Rowe Jun 4 '12 at 11:09
add comment

1 Answer

up vote 5 down vote accepted

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

  • Pro: Well established standard
  • Pro: Works with XML and JSON
  • Pro: Has excellent Java support through Apache Abdera
  • Con: Abdera introduces a lot of dependencies
  • Con: Very complex to work with on server side
  • Con: Difficult to build a complete JavaScript client

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

  • Pro: Introduces a lightweight and extensible approach
  • Pro: Works with XML and JSON
  • Pro: Trivial to create a JAXB model to implement it (no dependencies)
  • Pro: Provides a good linking framework
  • Pro: Trivial to create a JavaScript client using jQuery XML parsing
  • Con: Not ratified (although IETF have been approached)

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.