[DOCS] Add info about GET/POST to the API conventions. #74529

debadair · 2021-06-24T01:13:37Z

Note that Elasticsearch GET APIs that support a request body can also be submitted as POST requests.

debadair · 2021-06-24T21:15:47Z

@elasticmachine retest this please

debadair · 2021-06-28T19:55:23Z

@elasticmachine retest this please

elasticmachine · 2021-06-28T20:51:49Z

Pinging @elastic/es-core-infra (Team:Core/Infra)

elasticmachine · 2021-06-28T20:51:49Z

Pinging @elastic/es-docs (Team:Docs)

jrodewig

LGTM. I left some minor feedback but nothing blocking. Thanks!

jrodewig · 2021-06-28T20:58:59Z

docs/reference/api-conventions.asciidoc

+A number of {es} GET APIs--most notably the search API--support passing parameters
+in the body of the request. 


It may be simpler to just say support a request body.

As written, users could interpret this to mean I can pass any query parameters in the request body, which isn't usually true.

jrodewig · 2021-06-28T21:05:07Z

docs/reference/api-conventions.asciidoc

+While the GET action makes sense in the context of retrieving information, 
+GET requests with a body are not supported by all HTTP libraries.
+(RFC 7231 doesn't define how GET requests with a body should be handled, 
+so they are not allowed by all HTTP servers.)

-* <<multi-index>>
-* <<date-math-index-names>>
-* <<cron-expressions>>
-* <<common-options>>
-* <<url-access-control>>
+Because GET requests with bodies are not universally supported, 
+all {es} GET APIs that require a body can also be submitted as POST requests.


I'd combine these paragraphs and remove the parenthetical. Something like:

Because not all HTTP servers allow GET requests with a body, these APIs also support the POST method.

jrodewig · 2021-06-28T21:08:47Z

docs/reference/rest-api/common-options.asciidoc

+[discrete]
+[[api-conventions-parameters]]
+=== Parameters
+
+Rest parameters (when using HTTP, map to HTTP URL parameters) follow the
+convention of using underscore casing.
+
+[discrete]
+=== Boolean Values
+
+All REST API parameters (both request parameters and JSON body) support
+providing boolean "false" as the value `false` and boolean "true" as the
+value `true`. All other values will raise an error.
+
+[discrete]
+==== Number Values
+
+All REST APIs support providing numbered parameters as `string` on top
+of supporting the native JSON number types.
+
+[discrete]
+[[time-units]]
+=== Time units
+
+Whenever durations need to be specified, e.g. for a `timeout` parameter, the duration must specify
+the unit, like `2d` for 2 days. The supported units are:
+
+[horizontal]
+`d`::       Days
+`h`::       Hours
+`m`::       Minutes
+`s`::       Seconds
+`ms`::      Milliseconds
+`micros`::  Microseconds
+`nanos`::   Nanoseconds
+
+[[byte-units]]
+[discrete]
+=== Byte size units
+
+Whenever the byte size of data needs to be specified, e.g. when setting a buffer size
+parameter, the value must specify the unit, like `10kb` for 10 kilobytes. Note that
+these units use powers of 1024, so `1kb` means 1024 bytes. The supported units are:
+
+[horizontal]
+`b`::   Bytes
+`kb`::  Kilobytes
+`mb`::  Megabytes
+`gb`::  Gigabytes
+`tb`::  Terabytes
+`pb`::  Petabytes
+
+[[size-units]]
+[discrete]
+=== Unit-less quantities
+
+Unit-less quantities means that they don't have a "unit" like "bytes" or "Hertz" or "meter" or "long tonne".
+
+If one of these quantities is large we'll print it out like 10m for 10,000,000 or 7k for 7,000. We'll still print 87
+when we mean 87 though. These are the supported multipliers:
+
+[horizontal]
+`k`::  Kilo
+`m`::  Mega
+`g`::  Giga
+`t`::  Tera
+`p`::  Peta
+
+[[distance-units]]
+[discrete]
+=== Distance Units
+
+Wherever distances need to be specified, such as the `distance` parameter in
+the <<query-dsl-geo-distance-query>>), the default unit is meters if none is specified.
+Distances can be specified in other units, such as `"1km"` or
+`"2mi"` (2 miles).
+
+The full list of units is listed below:
+
+[horizontal]
+Mile::          `mi` or `miles`
+Yard::          `yd` or `yards`
+Feet::          `ft` or `feet`
+Inch::          `in` or `inch`
+Kilometer::     `km` or `kilometers`
+Meter::         `m` or `meters`
+Centimeter::    `cm` or `centimeters`
+Millimeter::    `mm` or `millimeters`
+Nautical mile:: `NM`, `nmi`, or `nauticalmiles`


I'd consider moving these sections to the conventions page as they're not really about options/parameters.

jrodewig · 2021-06-28T21:09:03Z

docs/reference/rest-api/common-options.asciidoc

+[discrete]
+=== Request body in query string
+
+For libraries that don't accept a request body for non-POST requests,
+you can pass the request body as the `source` query string parameter
+instead. When using this method, the `source_content_type` parameter
+should also be passed with a media type value that indicates the format
+of the source, such as `application/json`.
+
+[discrete]
+=== Content-type requirements
+
+The type of the content sent in a request body must be specified using
+the `Content-Type` header. The value of this header must map to one of
+the supported formats that the API supports. Most APIs support JSON,
+YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON,
+JSON, and SMILE; other types will result in an error response.
+
+When using the `source` query string parameter, the content type must be
+specified using the `source_content_type` query string parameter.
+
+{es} only supports UTF-8-encoded JSON. {es} ignores any other encoding headings
+sent with a request. Responses are also UTF-8 encoded.


I'd move these sections to the conventions page.

debadair · 2021-06-29T21:45:58Z

Thanks for the review! I streamlined things a bit more, moved the rest of the conventions to the conventions, and organized them in more logical groupings.

debadair · 2021-06-29T22:29:22Z

@elasticmachine retest this please

debadair · 2021-06-30T01:09:47Z

@elasticmachine retest this please

debadair · 2021-06-30T01:57:04Z

@elasticmachine retest this please

debadair · 2021-06-30T15:43:37Z

@elasticmachine retest this please

debadair · 2021-06-30T16:10:50Z

@elasticmachine retest this please

debadair force-pushed the get-body branch from 106e645 to 193c64e Compare June 24, 2021 23:11

[DOCS] Add info about GET/POST to the API conventions.

7f77c6d

debadair force-pushed the get-body branch from 94f5d04 to 7f77c6d Compare June 24, 2021 23:22

debadair added 2 commits June 28, 2021 13:04

Fixed anchor

d7daf8e

Added redirect

7d59d04

debadair requested review from gwbrown and jrodewig June 28, 2021 20:49

debadair added :Core/Infra/REST API REST infrastructure and utilities >docs General docs changes v7.14.0 v8.0.0 v7.13.3 labels Jun 28, 2021

debadair marked this pull request as ready for review June 28, 2021 20:51

elasticmachine added Team:Core/Infra Meta label for core/infra team Team:Docs Meta label for docs team labels Jun 28, 2021

debadair mentioned this pull request Jun 28, 2021

Updated link to ES API conventions elastic/stack-docs#1724

Closed

jrodewig approved these changes Jun 29, 2021

View reviewed changes

Incorporated review suggestions

0325317

This was referenced Jun 30, 2021

[DOCS] Update xrefs to time units section in ES guide elastic/stack-docs#1727

Merged

[DOCS] Updated xref to ES guide elastic/kibana#103803

Merged

[DOCS] Update xrefs to the units sections in the ES guide #74726

Merged

mark-vieira added v7.15.0 and removed v7.14.0 labels Jun 30, 2021

debadair merged commit 29bb8fd into elastic:master Jun 30, 2021

debadair removed v7.13.3 v7.15.0 labels Jul 1, 2021

debadair mentioned this pull request Jul 1, 2021

[DOCS] Added note about GET requests with bodies to API conventions #74805

Merged

jakelandis added v8.0.0-alpha1 and removed v8.0.0 labels Jul 26, 2021

jrodewig mentioned this pull request Nov 3, 2021

[DOCS] Updates outdated link in hidden data stream term elastic/stack-docs#1869

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Add info about GET/POST to the API conventions. #74529

[DOCS] Add info about GET/POST to the API conventions. #74529

debadair commented Jun 24, 2021

debadair commented Jun 24, 2021

debadair commented Jun 28, 2021

elasticmachine commented Jun 28, 2021

elasticmachine commented Jun 28, 2021

jrodewig left a comment

jrodewig Jun 28, 2021

jrodewig Jun 28, 2021

jrodewig Jun 28, 2021

jrodewig Jun 28, 2021

debadair commented Jun 29, 2021

debadair commented Jun 29, 2021

debadair commented Jun 30, 2021

debadair commented Jun 30, 2021

debadair commented Jun 30, 2021

debadair commented Jun 30, 2021

		A number of {es} GET APIs--most notably the search API--support passing parameters
		in the body of the request.

[DOCS] Add info about GET/POST to the API conventions. #74529

[DOCS] Add info about GET/POST to the API conventions. #74529

Conversation

debadair commented Jun 24, 2021

debadair commented Jun 24, 2021

debadair commented Jun 28, 2021

elasticmachine commented Jun 28, 2021

elasticmachine commented Jun 28, 2021

jrodewig left a comment

Choose a reason for hiding this comment

jrodewig Jun 28, 2021

Choose a reason for hiding this comment

jrodewig Jun 28, 2021

Choose a reason for hiding this comment

jrodewig Jun 28, 2021

Choose a reason for hiding this comment

jrodewig Jun 28, 2021

Choose a reason for hiding this comment

debadair commented Jun 29, 2021

debadair commented Jun 29, 2021

debadair commented Jun 30, 2021

debadair commented Jun 30, 2021

debadair commented Jun 30, 2021

debadair commented Jun 30, 2021