REST Complex/Composite/Nested Resources
I'm trying to wrap my head around the best way to address concepts in a REST based API. Flat resources that don't contain other resources are no problem. Where I'm running into trouble are the complex resources.
For instance, I have a resource for a comic book. ComicBook has all sorts of properties on it like author, issue number, date, etc.
A comic book also has a list of 1..n covers. These covers are complex objects. They contain a lot of information about the cover: the artist, a date, and even a base 64 encoded image of the cover.
For a GET on ComicBook I could just return the comic, and all of the covers including their base64'ed images. That's probably not a big deal for getting a single comic. But suppose I am building a client app that wants to list all of the comics in the system in a table.
The table will contain a few properties from the ComicBook resource, but we're certainly not going to want to display all the covers in the table. Returning 1000 comic books, each with multiple covers would result in a ridiculously large amount of data coming across the wire, data that isn't necessary to the end user in that case.
My instinct is to make Cover a resource and have ComicBook contain covers. So now Cover is a URI. GET on comic book works now, instead of the huge Cover resource we send back a URI for each cover and clients can retrieve the Cover resources as they require them.
Now I have a problem with creating new comics. Surely I'm going to want to create at least one cover when I create a Comic, in fact that's probably a business rule.
So now I'm stuck, I either force the clients to enforce business rules by first submitting a Cover, getting the URI for that cover, then POSTing a ComicBook with that URI in the list, or my POST on ComicBook takes in a different looking resource than it spits out. The incoming resources for POST and GET are deep copies, where the outgoing GETs contain references to dependent resources.
The Cover resource is probably necessary in any case because I'm sure as a client I'd want to address covers direction in some cases. So the problem exists in a general form regardless of the size of the dependent resource. In general how do you handle complex resources without forcing the client to just "know" how those resources are composed?
Answer
@ray, excellent discussion
@jgerman, don't forget that just because it's REST, doesn't mean resources have to be set in stone from POST.
What you choose to include in any given representation of a resource is up to you.
Your case of the the covers referenced separately is merely the creation of a parent resource (comic book) whose child resources (covers) may be cross-referenced. For example, you might also wish to provide references to authors, publishers , characters, or categories separately. You may wish to create these resources separately or before the comic book which references them as child resources. Alternatively, you may wish to create new child resources upon creation of the parent resource.
Your specific case of the covers is slightly more complex in that a cover really does require a comic book, and visa versa.
However, if you consider an email message as a resource, and the from address as a child resource, you can obviously still reference the from address separately. For example, get all from addresses. Or, create a new message with a previous from address. If email was REST, you could easily see that many cross-referenced resources could be available: /received-messages, /draft-messages, /from-addresses, /to-addresses, /addresses, /subjects, /attachments, /folders, /tags, /categories, /labels, et al.
This tutorial provides a great example of cross-referenced resources. http://www.peej.co.uk/articles/restfully-delicious.html
This is the most common pattern for automatically-generated data. For example, you don't post a URI, ID, or creation date for the new resource, as these are generated by the server. And yet, you can retrieve the URI, ID, or creation date when you get the new resource back.
An example in your case of binary data. For example, you want to post binary data as child resources. When you get the parent resource you can represent those child resources as the same binary data, or as URIs which represent the binary data.
Forms & parameters are already different than the HTML representations of the resources. Posting a binary/file parameter which results in a URL isn't a stretch.
When you get the form for a new resource (/comic-books/new), or get the form to edit a resource (/comic-books/0/edit), you are asking for a forms-specific representation of the resource. If you post it to the resource collection with content-type "application/x-www-form-urlencoded" or "multipart/form-data", you are asking the server to save that type representation. The server can respond with the HTML representation which was saved, or whatever.
You may want to also allow for an HTML, XML, or JSON represention to be posted to the resource collection, for purposes of an API or similar.
It is also possible to represent your resources and workflow as you describe, taking into account covers posted after the comic book, but requiring comic books to have a cover. Example as follows.
- Allows delayed cover creation
- Allows comic book creation with required cover
- Allows covers to be cross-referenced
- Allows multiple covers
- Create draft comic book
- Create draft comic book covers
- Publish draft comic book
GET /comic-books
=> 200 OK, Get all comic books.
GET /comic-books/0
=> 200 OK, Get comic book (id: 0) with covers (/covers/1, /covers/2).
GET /comic-books/0/covers
=> 200 OK, Get covers for comic book (id: 0).
GET /covers
=> 200 OK, Get all covers.
GET /covers/1
=> 200 OK, Get cover (id: 1) with comic book (/comic-books/0).
GET /comic-books/new
=> 200 OK, Get form to create comic book (form: POST /draft-comic-books).
POST /draft-comic-books
title=foo
author=boo
publisher=goo
published=2011-01-01
=> 302 Found, Location: /draft-comic-books/3, Redirect to draft comic book (id: 3) with covers (binary).
GET /draft-comic-books/3
=> 200 OK, Get draft comic book (id: 3) with covers.
GET /draft-comic-books/3/covers
=> 200 OK, Get covers for draft comic book (/draft-comic-book/3).
GET /draft-comic-books/3/covers/new
=> 200 OK, Get form to create cover for draft comic book (/draft-comic-book/3) (form: POST /draft-comic-books/3/covers).
POST /draft-comic-books/3/covers
cover_type=front
cover_data=(binary)
=> 302 Found, Location: /draft-comic-books/3/covers, Redirect to new cover for draft comic book (/draft-comic-book/3/covers/1).
GET /draft-comic-books/3/publish
=> 200 OK, Get form to publish draft comic book (id: 3) (form: POST /published-comic-books).
POST /published-comic-books
title=foo
author=boo
publisher=goo
published=2011-01-01
cover_type=front
cover_data=(binary)
=> 302 Found, Location: /comic-books/3, Redirect to published comic book (id: 3) with covers.