title: REST Complex/Composite/Nested Resources
body: <p>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.</p>
  
  <p>For instance, I have a resource for a comic book. <code>ComicBook</code> has all sorts of properties on it like <code>author</code>, <code>issue number</code>, <code>date</code>, etc. </p>
  
  <p>A comic book also has a list of <code>1..n</code> 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. </p>
  
  <p>For a <code>GET</code> on <code>ComicBook</code> 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.<br>
  The table will contain a few properties from the <code>ComicBook</code> 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. </p>
  
  <p>My instinct is to make <code>Cover</code> a resource and have <code>ComicBook</code> contain covers. So now <code>Cover</code> is a URI. <code>GET</code> on comic book works now, instead of the huge <code>Cover</code> resource we send back a URI for each cover and clients can retrieve the Cover resources as they require them.</p>
  
  <p>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 <code>Comic</code>, in fact that's probably a business rule.<br>
  So now I'm stuck, I either force the clients to enforce business rules by first submitting a <code>Cover</code>, getting the URI for that cover, then <code>POST</code>ing a <code>ComicBook</code> with that URI in the list, or my <code>POST</code> on <code>ComicBook</code> takes in a different looking resource than it spits out. The incoming resources for <code>POST</code> and <code>GET</code> are deep copies, where the outgoing <code>GET</code>s contain references to dependent resources. </p>
  
  <p>The <code>Cover</code> 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?</p>