[[api-conventions]]
== API Conventions
=== Generic Parameters
By default, all api methods accept the following parameters. They are omitted from the param lists of each method for brevity.

[horizontal]
`method`::
+
`String` -- The HTTP method to use for this request. All of the API methods have their own default.

`body`::
`String, Anything` -- The body to send along with this request. If the body is a string it will be passed along as is, otherwise it is passed to the serializer and converted to either JSON or a newline separated list of JSON objects based on the API method.
+
NOTE: the https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/sudo-suhas/elastic-builder[elastic-builder] or https://github.com/fullscale/elastic.js[elastic.js] libraries can be used to make building request bodies simpler.

`ignore`::
+
`Number, Number[]` -- HTTP status codes which should not be considered errors for this request.

`filterPath`::
+
`String|String[]` -- Starting in **elasticsearch 1.6** the `filterPath` parameter can be passed to any API to filter its reponse values. See the https://www.elastic.co/guide/en/elasticsearch/reference/5.0/common-options.html#common-options-response-filtering[elasticsearch response filtering docs] for more information.

=== Config values you can override per request
  * `requestTimeout` -- <<config-request-timeout, more info>>
  * `maxRetries` -- <<config-max-retries, more info>>

[[api-conventions-cb]]
=== Callbacks or Promises
When a callback is passed to any of the API methods, it will be called with `(err, response, status)`. If you prefer to use promises, don't pass a callback and a promise will be returned. The promise will either be resolved with the response body, or rejected with the error that occured (including any 300+ response for non "exists" methods).

Both styles of calling the API will return an object (either a promise or just a plain object) which has an `abort()` method. Calling that abort method ends the HTTP request, but it will not end the work Elasticsearch is doing.