<p dir="auto"><a href="https://twitter.com/mausch/status/530504035540160513" rel="nofollow">https://twitter.com/mausch/status/530504035540160513</a></p>
<p dir="auto"><a href="https://twitter.com/LeviNotik/status/530505312777023488" rel="nofollow">https://twitter.com/LeviNotik/status/530505312777023488</a></p>
<p dir="auto"><a href="https://twitter.com/mwotton/status/442775637648891904" rel="nofollow">https://twitter.com/mwotton/status/442775637648891904</a></p>
<p dir="auto"><a href="https://twitter.com/melvinmt/status/530474427306479616" rel="nofollow">https://twitter.com/melvinmt/status/530474427306479616</a></p>
<p dir="auto"><a href="https://twitter.com/kosmikko/status/502340971527671808" rel="nofollow">https://twitter.com/kosmikko/status/502340971527671808</a></p>
<p dir="auto"><a href="https://twitter.com/kenperkins/status/494173990152175617" rel="nofollow">https://twitter.com/kenperkins/status/494173990152175617</a> (navigation, I've had this problem and I'm a relatively experienced user of the site and ES itself)</p>
<p dir="auto"><a href="https://twitter.com/icyliquid/status/477500839020752896" rel="nofollow">https://twitter.com/icyliquid/status/477500839020752896</a></p>
<p dir="auto"><a href="https://twitter.com/werg/status/466733972324880384" rel="nofollow">https://twitter.com/werg/status/466733972324880384</a> (another suggestion to bypass official ES documentation)</p>
<p dir="auto">I wrote <a href="https://github.com/bitemyapp/bloodhound">https://github.com/bitemyapp/bloodhound</a> partly because I was having a hell of a time generating valid Elasticsearch requests without lots of copy-paste and templating.</p>
<p dir="auto">The docs have not been improved much in the last couple years other than when you did the big site change.</p>
<p dir="auto">It's extremely hard for a new user of Elasticsearch to get a bird's eye view.</p>
<p dir="auto">I brought up Bloodhound when I first released it as a way to possibly start a proper spec of what Elasticsearch accepts as a valid request and what it does not. I'd like to revive the idea of having a spec so that users and client implementors don't have to keep rediscovering how Elasticsearch works through haphazard experimentation.</p>
<p dir="auto">Back when I was implementing Bloodhound I asked if there was a spec. I was told there wasn't one. I was briefly hopeful when I saw there was a Thrift spec...but it passes off the actual document structure as a JSON blob, lending no useful information.</p>
<p dir="auto">Please at least consider having a spec for the API.</p>
<p dir="auto">Requests/queries/etc currently have custom parsers, which make it more difficult to be certain that they are error free.  We should replace all this hand parsing with some form of grammar, which defines exactly what syntax is allowed. This will also benefit those implementing clients, as they will have a grammar that can be interrogated programmatically.</p>
<p dir="auto">Any unknown parameters should throw a parsing exception.</p>
<p dir="auto">We can add custom rules where needed (eg to disallow certain combinations of parameters like using <code class="notranslate">fuzzy</code> in the <code class="notranslate">multi_match</code> query with type <code class="notranslate">cross_fields</code>).</p>