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]: opensearch-project/OpenSearch#16702 [2]: https://opensearch.org/docs/latest/api-reference/tasks/#attaching-headers-to-tasks Signed-off-by: Andrew Ross <[email protected]>
opensearch-project · Nov 26, 2024 · ac889b5 · ac889b5
1 parent 676dd77
commit ac889b5
Showing 1 changed file with 14 additions and 1 deletion.
diff --git 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` 
+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 different 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
+```