From b8e95cbb9a4495fce8566facff03a58bc27bcb8c Mon Sep 17 00:00:00 2001 From: Andrew Ross Date: Tue, 26 Nov 2024 13:40:46 -0800 Subject: [PATCH 1/6] Document the `X-Opaque-Id` header A [bug][1] was recently identified related to this header that was partly exascerbated by a misuse of the field. We have some documentation related to the [Tasks][2] API for this field, but no general guidance on how to use it. [1]: https://github.com/opensearch-project/OpenSearch/issues/16702 [2]: https://opensearch.org/docs/latest/api-reference/tasks/#attaching-headers-to-tasks Signed-off-by: Andrew Ross --- _api-reference/common-parameters.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/_api-reference/common-parameters.md b/_api-reference/common-parameters.md index 5b536ad992..21857c3125 100644 --- a/_api-reference/common-parameters.md +++ b/_api-reference/common-parameters.md @@ -123,4 +123,17 @@ Kilometers | `km` or `kilometers` Meters | `m` or `meters` Centimeters | `cm` or `centimeters` Millimeters | `mm` or `millimeters` -Nautical miles | `NM`, `nmi`, or `nauticalmiles` \ No newline at end of file +Nautical miles | `NM`, `nmi`, or `nauticalmiles` + +## `X-Opaque-Id` Header + +You can specify an opaque identifier on any request using the `X-Opaque-Id` header. This identifier is used to track tasks and deduplicate deprecation warnings in server side logs. This identifier is intended to differentiate callers into your OpenSearch cluster. Do not specify a unique value per request. + +#### Example request + +The following request adds an opaque ID to the request: + +```json + +curl -H "X-Opaque-Id: my-curl-client-1" -XGET localhost:9200/_tasks +``` From ed5806c10958e28141f4f53be461368c2ac7fffd Mon Sep 17 00:00:00 2001 From: Andrew Ross Date: Mon, 2 Dec 2024 18:28:16 -0600 Subject: [PATCH 2/6] Update _api-reference/common-parameters.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Andrew Ross --- _api-reference/common-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/common-parameters.md b/_api-reference/common-parameters.md index 21857c3125..9966d72fb2 100644 --- a/_api-reference/common-parameters.md +++ b/_api-reference/common-parameters.md @@ -127,7 +127,7 @@ Nautical miles | `NM`, `nmi`, or `nauticalmiles` ## `X-Opaque-Id` Header -You can specify an opaque identifier on any request using the `X-Opaque-Id` header. This identifier is used to track tasks and deduplicate deprecation warnings in server side logs. This identifier is intended to differentiate callers into your OpenSearch cluster. Do not specify a unique value per request. +You can specify an opaque identifier on any request using the `X-Opaque-Id` header. This identifier is used to track tasks and deduplicate deprecation warnings in server side logs. This identifier is intended to differentiate callers sending requests to your OpenSearch cluster. Do not specify a unique value per request. #### Example request From aa75a8baaf81f523bed081ab73742911c8681fe2 Mon Sep 17 00:00:00 2001 From: Andrew Ross Date: Mon, 2 Dec 2024 18:28:22 -0600 Subject: [PATCH 3/6] Update _api-reference/common-parameters.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Andrew Ross --- _api-reference/common-parameters.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_api-reference/common-parameters.md b/_api-reference/common-parameters.md index 9966d72fb2..26fb46f910 100644 --- a/_api-reference/common-parameters.md +++ b/_api-reference/common-parameters.md @@ -134,6 +134,5 @@ You can specify an opaque identifier on any request using the `X-Opaque-Id` head The following request adds an opaque ID to the request: ```json - curl -H "X-Opaque-Id: my-curl-client-1" -XGET localhost:9200/_tasks ``` From 4a31c84a523d404babc5ca33593714459acaca41 Mon Sep 17 00:00:00 2001 From: Andrew Ross Date: Mon, 2 Dec 2024 18:28:28 -0600 Subject: [PATCH 4/6] Update _api-reference/common-parameters.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Andrew Ross --- _api-reference/common-parameters.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_api-reference/common-parameters.md b/_api-reference/common-parameters.md index 26fb46f910..77d44dc07e 100644 --- a/_api-reference/common-parameters.md +++ b/_api-reference/common-parameters.md @@ -136,3 +136,4 @@ The following request adds an opaque ID to the request: ```json curl -H "X-Opaque-Id: my-curl-client-1" -XGET localhost:9200/_tasks ``` +{% include copy.html %} From bad63af47fb073250b0f5f608912feeb49c4201d Mon Sep 17 00:00:00 2001 From: Andrew Ross Date: Tue, 3 Dec 2024 12:27:13 -0600 Subject: [PATCH 5/6] Update _api-reference/common-parameters.md Co-authored-by: Nathan Bower Signed-off-by: Andrew Ross --- _api-reference/common-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/common-parameters.md b/_api-reference/common-parameters.md index 77d44dc07e..c873a46c0b 100644 --- a/_api-reference/common-parameters.md +++ b/_api-reference/common-parameters.md @@ -127,7 +127,7 @@ Nautical miles | `NM`, `nmi`, or `nauticalmiles` ## `X-Opaque-Id` Header -You can specify an opaque identifier on any request using the `X-Opaque-Id` header. This identifier is used to track tasks and deduplicate deprecation warnings in server side logs. This identifier is intended to differentiate callers sending requests to your OpenSearch cluster. Do not specify a unique value per request. +You can specify an opaque identifier for any request using the `X-Opaque-Id` header. This identifier is used to track tasks and deduplicate deprecation warnings in server-side logs. This identifier is used to differentiate between callers sending requests to your OpenSearch cluster. Do not specify a unique value per request. #### Example request From 4c8f6518cac244c1ecda9734202c2a095268558e Mon Sep 17 00:00:00 2001 From: Andrew Ross Date: Tue, 3 Dec 2024 12:27:21 -0600 Subject: [PATCH 6/6] Update _api-reference/common-parameters.md Co-authored-by: Nathan Bower Signed-off-by: Andrew Ross --- _api-reference/common-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/common-parameters.md b/_api-reference/common-parameters.md index c873a46c0b..ac3efbf4bf 100644 --- a/_api-reference/common-parameters.md +++ b/_api-reference/common-parameters.md @@ -125,7 +125,7 @@ Centimeters | `cm` or `centimeters` Millimeters | `mm` or `millimeters` Nautical miles | `NM`, `nmi`, or `nauticalmiles` -## `X-Opaque-Id` Header +## `X-Opaque-Id` header You can specify an opaque identifier for any request using the `X-Opaque-Id` header. This identifier is used to track tasks and deduplicate deprecation warnings in server-side logs. This identifier is used to differentiate between callers sending requests to your OpenSearch cluster. Do not specify a unique value per request.