title: REST API - attribute filter in media type parameters
body: <p>I want to seek some advise regarding designing REST / hipermedia API and in particular regarding implementation with <a href="http://django-rest-framework.org/" rel="nofollow">django-rest</a> framework.</p>
  
  <p>Instead the generic 'entity' example, I will use a more mundane 'document' entity.</p>
  
  <p><strong>Question 1.</strong></p>
  
  <pre><code>GET /document/?[query]
  </code></pre>
  
  <p>gets a list of documents. The issue is that 'document' has few dozens of attributes and in many cases the client would care only for a few (especially in this search) - the size of the response may differ like several (up to 10) times, and also server queries may be faster. Also, I have to mention that we prefer to be schema-less.</p>
  
  <p>I found samples like</p>
  
  <pre><code>GET /document/attr1, attr2../?[query]
  </code></pre>
  
  <p>which i find quite un-REST-ful.</p>
  
  <p>Another article was suggesting to use Content-Types (in fact Accept, as it is for requests), but example was missing and still have mixed feeling. Something like:</p>
  
  <pre><code>Accept: application/json; attrs="attr1,attr2"
  </code></pre>
  
  <p>I am not sure if this is respecting the semantics of HTTP, and also if such use of media type parameters is appropriate (after all I want a different representation of resource - with some attributes filtered out).</p>
  
  <p><strong>Question 2.</strong></p>
  
  <p>If the above is more or less aceptable solution, I wonder if there is something ready in <a href="http://django-rest-framework.org/" rel="nofollow">django-rest</a> regarding parsing of custom media type attributes. From what i can see in he docs, media type parameters are not separately parsed (or handled).</p>
  
  <p><strong>Edit</strong></p>
  
  <p>Some additional info: large part of the application is OLTP (with will not be cacheable). Architecture is JSON server with static files, JS heavy client.</p>
  
  <p><strong>Edit 2</strong></p>
  
  <p>Actually, I found some opinions that searches in their nature are creation of new (volatile) resource (the result), so POST method is more appropriate. This eliminates the issue under discussion. I have some problems with the created entity (result), as I don't want to have to persist it, but I think this is not compulsory. The question is what to put in 'Location' header (bogus URL, no Location header or else)? The only consistent behavior for me is exactly what I do not want to do - search POST performs the search, stores the result on server side and returns 201 with link to it. This, however, is unjustified persistence load...</p>
  
  <p>Regarding browser testing, MIME type text/html may present a user friendly form for searching.</p>