title: Should REST API combine information from multiple tables into JSON response?
body: <p>I am looking for a discussion on REST API standard patterns.  I have an implementation in a NoSQL style ... that is, there is one table that contains objects (Agenda Items) which each have a list of references to records in another table (Documents).  In the UI I am building, a user can select an existing Attachment, and attach it to the Agenda Item.  You can not, in this UI, create new Document objects, only refer to existing ones.  Since this is a NoSQL implementation, I am not joining the tables on the doc_id, but manipulating them as separate tables.</p>
  
  <p>There are two ways to implement the REST api.  First is <strong>denormalized</strong> where one request gets the Agenda Item records, and a second request gets the Documents.  Using the doc_id from the Agenda Item, in client you find the associated document information.</p>
  
  <pre><code>[
     {
      "name": "Agenda Item 1",
      "attachments": ["11556", "87544"]
      },
     {
      "name": "Agenda Item 2",
      "attachments": ["33445", "87544"]
      }
  ]
  </code></pre>
  
  <p>and the document list is:</p>
  
  <pre><code>[
     {
      "name": "Design Spec A.ppt",
      "id": "11556"
     },
     {
      "name": "Design Guidelines.doc",
      "id": "33455"
     },
     {
      "name": "User Studies.xls",
      "id": "87544"
     },
  ]
  </code></pre>
  
  <p>The second approach is to construct the REST such that the JSON representation of the Agenda Item includes all the document details within one request.  I will call this <strong>trashy</strong> because there is extra information that did not come from the table.</p>
  
  <pre><code>[
     {
      "name": "Agenda Item 1",
      "attachments": [{
          "name": "Design Spec A.ppt",
          "id": "11556"
        }, 
        {
          "name": "User Studies.xls",
          "id": "87544"
        }]
      },
     {
      "name": "Agenda Item 2",
      "attachments": [{
          "name": "Design Guidelines.doc",
          "id": "33455"
        }, 
        {
          "name": "User Studies.xls",
          "id": "87544"
        }]
      }
  ]
  </code></pre>
  
  <p>The latter format is </p>
  
  <ul>
  <li><em>convenient</em> for the client because in a single request you get all the information you need to present a nice display to the user.  </li>
  <li><em>inefficient</em> because the information about one document is sent twice. (It might be in general a lot more information than this example.) </li>
  <li><em>trashy</em> because if you POST this same format back in an update command, the extra details about the document should be ignored -- only the id is relevant for updates.  If you were to change the name of a document in this structure, presumably that document would NOT be updated with the new name.  Because the document appears twice in this structure, there is the potential that it has a different name at different points.</li>
  </ul>
  
  <p>Seems that the rule might be that you add in the extra document information when GETTING the information, and ignore that extra information when PUTTING or POSTING the JSON structure.</p>
  
  <p>A third option is the <strong>hybrid</strong>:  You get the fat filled-in form, but you PUT back the lean denormalized form.  I would prefer not to have two different formats for the same object.  I am using AngularJS and the fetched JSON objects translate directly in JS object trees, and it is mighty convenient to put the exact same thing back.   </p>
  
  <p>I have implemented both, and both approaches work, but I would like pointed to a discussion about: what is the wisdom of each approach?  </p>
  
  <p>Also, when using AngularJS, it is very convenient to put additional members into collection for the UI, for example a "selected" flag.  Again, maybe I am too lazy, but stripping this selected flag out of each record before posting back for updates is a bother, and if I can assume that extra 'trashy' data members will be ignored it makes the coding a lot easier.  Is it OK to assume that your REST API will ignore extra elements?</p>