REST Solutions for Complex Data Structures

Question

I'm currently architecting an API and one solution we are leaning towards is to use REST. A key issue is the parameters being passed are complex data types including nested hashes, hashes of arrays of hashes, etc. The philosophy is that the user should be able to complete their tasks with a minimum number of API calls.

One common solution I've seen is to post serialized data, however, this would require clients to manage serializing their own data. Our current API uses XMLRPC and clients can just use a compatible client and not worry about serialization.

My question is for the community, for others that had to come up with a solution to solve this problem, what did you do? What were the costs/tradeoffs? What would you do differently?

Thanks :)

Answer 1

REST is all about transferring representations of the states of resources over the network. So don't think about parameters, think about what your resources are, and what the best representations of those resources would be.

And remember that representation transfer is two ways -- clients can send representations of the desired states of resources in order to create or update resources. That's what POST and PUT are for.

Also, don't overlook how valuable it can be for a resource to provide/support multiple representation formats (Content Types). I have built many APIs where a resource can provide an HTML representation for browsers, or a JSON or XML representation for programmatic usage.

To be a little more specific, for the types of data structures you describe, I'd recommend JSON. It's simple, clear, easy to work with on any platform, and succinctly and directly supports those structures.