REST Complex/Composite/Nested Resources [closed]

Question

@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:

1. 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.

2. 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.