title: GET HTTP request payload
body: <p>I am designing an API and I wonder if it is fine to send a JSON payload on a GET request?</p>
  <p>In this other question <a href="https://stackoverflow.com/questions/5905916/payloads-of-http-request-methods">Payloads of HTTP Request Methods</a>, we can find according to <a href="https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p2-semantics-14" rel="nofollow noreferrer">this link</a>:</p>
  <ul>
  <li>HEAD - No defined body semantics.</li>
  <li>GET - No defined body semantics.</li>
  <li>PUT - Body supported.</li>
  <li>POST - Body supported.</li>
  <li>DELETE - No defined body semantics.</li>
  <li>TRACE - Body not supported.</li>
  <li>OPTIONS - Body supported but no semantics (maybe in the future).</li>
  </ul>
  <p><strong>Does this mean that I should not send a GET request with a payload?</strong>
  Are there risks to do so?</p>
  <ul>
  <li>Like having some HTTP client libraries incapable of sending such a payload?</li>
  <li>Or my Java API code not being portable on certain application servers?</li>
  <li>Anything else?</li>
  </ul>
  <hr />
  <p>I found out that ElasticSearch was using such a payload on a GET request:</p>
  <pre><code>$ curl -XGET 'http://localhost:9200/twitter/tweet/_search?routing=kimchy' -d '{
      &quot;query&quot;: {
          &quot;filtered&quot; : {
              &quot;query&quot; : {
                  &quot;query_string&quot; : {
                      &quot;query&quot; : &quot;some query string here&quot;
                  }
              },
              &quot;filter&quot; : {
                  &quot;term&quot; : { &quot;user&quot; : &quot;kimchy&quot; }
              }
          }
      }
  }
  '
  </code></pre>
  <p>So if this popular libary does it and nobody complains, then perhaps I can do the same?</p>
  <p>By the way, <strong>I would like to know if this is OK to mix queryString parameters and JSON payload?</strong> Exactly like this ElasticSearch query does. If so, are there rules so that we know which arguments should be queryString parameters, or payload parameters?</p>
  <hr />
  <p>Here we can read:
  <a href="https://stackoverflow.com/questions/978061/http-get-with-request-body">HTTP GET with request body</a></p>
  <blockquote>
  <p>Roy Fielding's comment about including a body with a GET request.</p>
  <p>Yes. In other words, any HTTP request message is allowed to contain a
  message body, and thus must parse messages with that in mind. Server
  semantics for GET, however, are restricted such that a body, if any,
  has no semantic meaning to the request. The requirements on parsing
  are separate from the requirements on method semantics.</p>
  <p>So, yes, you can send a body with GET, and no, it is never useful to
  do so.</p>
  <p>This is part of the layered design of HTTP/1.1 that will become clear
  again once the spec is partitioned (work in progress).</p>
  <p>....Roy</p>
  </blockquote>
  <p>Then I don't really understand why it is never useful, because it makes sense in my opinion to send complex queries to the server that wouldn't fit well on queryParam or matrixParam.
  I think ElasticSearch API designers think the same...</p>
  <hr />
  <p>I am planning to design an API which can be called like that:</p>
  <pre><code>curl -XGET 'http://localhost:9000/documents/inbox?pageIndex=0&amp;pageSize=10&amp;sort=title'
  
  curl -XGET 'http://localhost:9000/documents/trash?pageIndex=0&amp;pageSize=10&amp;sort=title'
  
  curl -XGET 'http://localhost:9000/documents/search?pageIndex=0&amp;pageSize=10&amp;sort=title' -d '{
      &quot;someSearchFilter1&quot;:&quot;filterValue1&quot;,
      &quot;someSearchFilter2&quot;:&quot;filterValue2&quot;,
      &quot;someSearchFilterList&quot;: [&quot;filterValue3&quot;,&quot;xxx&quot;]
      ... a lot more ...
  }
  '
  </code></pre>
  <p><strong>Does it seem fine to you?</strong> Based on the above considerations.</p>
  <hr />