title: Different RESTful representations of the same resource
body: <p>My application has a resource at <code>/foo</code>. Normally, it is represented by an HTTP response payload like this:</p>
  
  <pre><code>{"a": "some text", "b": "some text", "c": "some text", "d": "some text"}
  </code></pre>
  
  <p>The client doesn't always need all four members of this object. What is the <strong>RESTfully semantic</strong> way for the client to tell the server what it needs in the representation? e.g. if it wants:</p>
  
  <pre><code>{"a": "some text", "b": "some text", "d": "some text"}
  </code></pre>
  
  <p>How should it <code>GET</code> it? Some possibilities (I'm looking for correction if I misunderstand REST):</p>
  
  <ul>
  <li><code>GET /foo?sections=a,b,d</code>.
  
  <ul>
  <li>The query string (called a <em>query</em> string after all) seems to mean "find resources matching this condition and tell me about them", not "represent this resource to me according to this customization".</li>
  </ul></li>
  <li><code>GET /foo/a+b+d</code> My favorite <strong>if REST semantics doesn't cover this issue</strong>, because of its simplicity.
  
  <ul>
  <li>Breaks URI opacity, violating HATEOAS.</li>
  <li>Seems to break the distinction between resource (the sole meaning of a URI is to identify one resource) and representation. But that's debatable because it's consistent with <code>/widgets</code> representing a presentable list of <code>/widget/&lt;id&gt;</code> resources, which I've never had a problem with.</li>
  </ul></li>
  <li>Loosen my constraints, respond to <code>GET /foo/a</code>, etc, and have the client make a request per component of <code>/foo</code> it wants.
  
  <ul>
  <li>Multiplies overhead, which can become a nightmare if <code>/foo</code> has hundreds of components and the client needs 100 of those.</li>
  <li>If I want to support an HTML representation of <code>/foo</code>, I have to use Ajax, which is problematic if I just want a single HTML page that can be crawled, rendered by minimalist browsers, etc.</li>
  <li>To maintain HATEOAS, it also requires links to those "sub-resources" to exist within other representations, probably in <code>/foo</code>: <code>{"a": {"url": "/foo/a", "content": "some text"}, ...}</code></li>
  </ul></li>
  <li><code>GET /foo</code>, <code>Content-Type: application/json</code> and <code>{"sections": ["a","b","d"]}</code> in the request body.
  
  <ul>
  <li>Unbookmarkable and uncacheable.</li>
  <li>HTTP does not define body semantics for <code>GET</code>. It's legal HTTP but how can I guarantee some user's proxy doesn't strip the body from a <code>GET</code> request?</li>
  <li>My <a href="https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en" rel="noreferrer" title="REST client">REST client</a> won't let me put a body on a <code>GET</code> request so I can't use that for testing.</li>
  </ul></li>
  <li>A custom HTTP header: <code>Sections-Needed: a,b,d</code>
  
  <ul>
  <li>I'd rather avoid custom headers if possible.</li>
  <li>Unbookmarkable and uncacheable.</li>
  </ul></li>
  <li><code>POST /foo/requests</code>, <code>Content-Type: application/json</code> and <code>{"sections": ["a","b","d"]}</code> in the request body. Receive a <code>201</code> with <code>Location: /foo/requests/1</code>. Then <code>GET /foo/requests/1</code> to receive the desired representation of <code>/foo</code>
  
  <ul>
  <li>Clunky; requires back-and-forth and some weird-looking code.</li>
  <li>Unbookmarkable and uncacheable since <code>/foo/requests/1</code> is just an alias that would only be used once and only kept until it is requested.</li>
  </ul></li>
  </ul>