REST Complex/Composite/Nested Resources [closed]
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?
@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.
Treating covers as resources is definitely in the spirit of REST, particularly HATEOAS. So yes, a GET request to http://example.com/comic-books/1 would give you a representation of book 1, with properties including a set of URIs for covers. So far so good.
Your question is how to deal with comic book creation. If your business rule was that a book would have 0 or more covers, then you have no problem:
POST http://example.com/comic-books
with coverless comic book data will create a new comic book and return the server generated id (lets say it comes back as 8), and now you can add covers to it like so:
POST http://example.com/comic-books/8/covers
with the cover in the entity body.
Now you have a good question which is what happens if your business rule says there always must be at least one cover. Here are some choices, the first of which you identified in your question:
Force the creation of a cover first, now essentially making cover a non-dependent resource, or you place the initial cover in the entity body of the POST that creates the comic book. This as you say means that the representation you POST to create will differ from the representation you GET.
Define the notion of a primary, or initial, or preferred, or otherwise-designated cover. This is likely a modeling hack, and if you did that it would be like tweaking your object model (your conceptual or business model) in order to fit a technology. Not a great idea.
You should weigh these two choices against simply allowing coverless comics.
Which of the three choices should you take? Not knowing too much about your situation, but answer the general 1..N dependent resource question, I would say:
If you can go with 0..N for your RESTful service layer, great. Perhaps a layer between your RESTful SOA can handle the further business constraint if at least one is required. (Not sure how that would look but it might be worth exploring.... end users don't usually see the SOA anyway.)
If you simply must model a 1..N constraint, then ask yourself whether covers might just be sharable resources, in other words, they might exist on things other than comic books. Now they are not dependent resources and you can create them first and supply URIs in your POST that creates comic books.
If you need 1..N and covers remain dependent, simply relax your instinct to keep the representations in POST and GET the same, or make them the same.
The last item is explained like so:
<comic-book>
<name>...</name>
<edition>...</edition>
<cover-image>...BASE64...</cover-image>
<cover-image>...BASE64...</cover-image>
<cover>...URI...</cover>
<cover>...URI...</cover>
</comic-book>
When you POST you allow existing uris if you have them (borrowed from other books) but also put in one or more initial images. If you are creating a book and your entity has no initial cover-image, return a 409 or similar response. On GET you can return URIs..
So basically you're allowing the POST and GET representations to "be the same" but you just choose not to "use" cover-image on GET nor cover on POST. Hope that makes sense.