api-ref: Add X-Openstack-Request-Id description

Add the description for the following items
in the API reference and the API guide.

* 'X-Openstack-Request-Id' header in request
* 'X-Openstack-Request-Id' header in response
* 'X-Compute-Request-Id' in response

Change-Id: Idd9181c1530eb9576da9941416b697a97c0cfb8d
Closes-Bug: #1693555

3 files changed, 62 insertions, 4 deletions

diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index e573c4b646..3e651881b2 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -12,6 +12,7 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 
 .. include:: versions.inc
 .. include:: urls.inc
+.. include:: request-ids.inc
 .. include:: servers.inc
 .. include:: servers-actions.inc
 .. include:: servers-action-fixed-ip.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 3312a56608..be3eb06ef7 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -26,14 +26,47 @@ tag_location:
   required: true
   type: string
   min_version: 2.26
-x-openstack-request-id:
+x-compute-request-id_resp:
   description: |
-    A unique ID for tracking the request. The request ID associated with the request
-    appears in the log lines for that request. By default, the middleware configuration
-    ensures that the request ID appears in the log files.
+    The local request ID, which is a unique ID generated automatically
+    for tracking each request to nova.
+    It is associated with the request and appears in the log lines
+    for that request.
+    By default, the middleware configuration
+    ensures that the local request ID appears in the log files.
+
+    .. note::
+
+       This header exists for backward compatibility.
+  in: header
+  required: true
+  type: string
+x-openstack-request-id_req:
+  description: |
+    The global request ID, which is a unique common ID
+    for tracking each request in OpenStack components.
+    The format of the global request ID must be ``req-`` + UUID (UUID4).
+    If not in accordance with the format, it is ignored.
+    It is associated with the request and appears in the log lines
+    for that request.
+    By default, the middleware configuration ensures that
+    the global request ID appears in the log files.
+  in: header
+  required: false
+  type: string
+  min_version: 2.46
+x-openstack-request-id_resp:
+  description: |
+    The local request ID, which is a unique ID generated automatically
+    for tracking each request to nova.
+    It is associated with the request and appears in the log lines
+    for that request.
+    By default, the middleware configuration
+    ensures that the local request ID appears in the log files.
   in: header
   required: true
   type: string
+  min_version: 2.46
 
 # variables in path
 agent_build_id:
diff --git a/api-ref/source/request-ids.inc b/api-ref/source/request-ids.inc
new file mode 100644
index 0000000000..76c0efafed
--- /dev/null
+++ b/api-ref/source/request-ids.inc
@@ -0,0 +1,24 @@
+.. -*- rst -*-
+
+===========
+Request IDs
+===========
+
+Users can specify the global request ID in the request header.
+Users can receive the local request ID in the response header.
+
+For more details about Request IDs, please reference: `Faults
+<https://developer.openstack.org/api-guide/compute/faults.html>`_
+
+**Request**
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: x-openstack-request-id_req
+
+**Response**
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Compute-Request-Id: x-compute-request-id_resp
+  - X-Openstack-Request-Id: x-openstack-request-id_resp