33 lines
2.0 KiB
Plaintext
Executable File
33 lines
2.0 KiB
Plaintext
Executable File
[[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/fullscale/elastic.js[elastic.js] or https://github.com/danpaz/bodybuilder[bodybuilder] 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.
|