title: REST API including and excluding of subresources
body: <p>I am trying to determine a RESTful way to have subresources included and excluded at will for specific requests. </p>
  
  <p>For example sake, this could be the original request:</p>
  
  <p><strong>GET departments/321</strong></p>
  
  <pre><code>200 (Ok)
  {
      "id": "321",
      "name": "Sales",
      "building": "The Foundary"
      "subdepartments": [
         {
            "id": "123",
            "name": "Training"
         },
         {
            "id": "224",
            "name": "Book Sales"
         }
         ...
      ]
  }
  </code></pre>
  
  <p>There could be a big list of sub departments.  The <code>GET departments</code> resource would also then include every department AND each of those departments' subdepartments. A lot of data.</p>
  
  <p>This could be solved by creating two separate resources:</p>
  
  <p><strong>GET departments/321</strong></p>
  
  <pre><code>200 (Ok)
  {
      "id": "3",
      "name": "Sales",
      "building": "The Foundary"
  }
  </code></pre>
  
  <p><strong>GET departments/321/subdepartments</strong></p>
  
  <pre><code>200 (Ok)
  [
     {
        "id": "123",
        "name": "Training"
     },
     {
        "id": "224",
        "name": "Book Sales"
     }
     ...
  ]
  </code></pre>
  
  <p>But there may be occasions where the client software would prefer not to make multiple requests (for performance sake most likely). Perhaps by providing an <code>include</code> filter:</p>
  
  <p><strong>GET departments/321?include=subdepartments</strong></p>
  
  <pre><code>200 (Ok)
  {
      "id": "321",
      "name": "Sales",
      "building": "The Foundary"
      "subdepartments": [
         {
            "id": "123",
            "name": "Training"
         },
         {
            "id": "224",
            "name": "Book Sales"
         }
         ...
      ]
  }
  </code></pre>
  
  <p>Or an exclude filter:</p>
  
  <p><strong>GET departments/321?exclude=subdepartments</strong></p>
  
  <pre><code>200 (Ok)
  {
      "id": "321",
      "name": "Sales",
      "building": "The Foundary"
  }
  </code></pre>
  
  <p>Although perhaps we need to include a link to the subresource if its excluded?</p>
  
  <p><strong>GET departments/321?exclude=subdepartments</strong></p>
  
  <pre><code>200 (Ok)
  {
      "id": "321",
      "name": "Sales",
      "building": "The Foundary"
      "subdepartments": {
          "href" : "api.com/departments/321/subresources"
      }
  }
  </code></pre>
  
  <p><strong>Is there an acceptable RESTful way of performing the above including or excluding of subresources?</strong></p>