Closes #11254: Introduce the X-Request-ID HTTP header to annotate the unique ID of each request for change logging

docs/features/change-logging.md

@@ -1,9 +1,13 @@
 # Change Logging
 
-Every time an object in NetBox is created, updated, or deleted, a serialized copy of that object taken both before and after the change is saved to the database, along with meta data including the current time and the user associated with the change. These records form a persistent record of changes both for each individual object as well as NetBox as a whole. The global change log can be viewed by navigating to Other > Change Log.
+Every time an object in NetBox is created, updated, or deleted, a serialized copy of that object taken both before and after the change is saved to the database, along with metadata including the current time and the user associated with the change. These records form a persistent record of changes both for each individual object as well as NetBox as a whole. The global change log can be viewed by navigating to Other > Change Log.
 
 A serialized representation of the instance being modified is included in JSON format. This is similar to how objects are conveyed within the REST API, but does not include any nested representations. For instance, the `tenant` field of a site will record only the tenant's ID, not a representation of the tenant.
 
 When a request is made, a UUID is generated and attached to any change records resulting from that request. For example, editing three objects in bulk will create a separate change record for each  (three in total), and each of those objects will be associated with the same UUID. This makes it easy to identify all the change records resulting from a particular request.
 
 Change records are exposed in the API via the read-only endpoint `/api/extras/object-changes/`. They may also be exported via the web UI in CSV format.
+
+## Correlating Changes by Request
+
+Every request made to NetBox is assigned a random unique ID that can be used to correlate change records. For example, if you change the status of three sites using the UI's bulk edit feature, you will see three new change records (one for each site) all referencing the same request ID. This shows that all three changes were made as part of the same request.

docs/integrations/rest-api.md

@@ -586,7 +586,6 @@ Additionally, a token can be set to expire at a specific time. This can be usefu
 
 Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.)
 
-
 ### Authenticating to the API
 
 An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token:
@@ -654,3 +653,22 @@ Note that we are _not_ passing an existing REST API token with this request. If
     "description": ""
 }
 ```
+
+## HTTP Headers
+
+### `API-Version`
+
+This header specifies the API version in use. This will always match the version of NetBox installed. For example, NetBox v3.4.2 will report an API version of `3.4`.
+
+### `X-Request-ID`
+
+!!! info "This feature was introduced in NetBox v3.5."
+
+This header specifies the unique ID assigned to the received API request. It can be very handy for correlating a request with change records. For example, after creating several new objects, you can filter against the object changes API endpoint to retrieve the resulting change records:
+
+```
+GET /api/extras/object-changes/?request_id=e39c84bc-f169-4d5f-bc1c-94487a1b18b5
+```
+
+!!! note
+    This header is included with _all_ NetBox responses, although it is most practical when working with an API.

docs/release-notes/version-3.5.md

@@ -2,6 +2,10 @@
 
 ## v3.5.0 (FUTURE)
 
+### Enhancements
+
+* [#11254](https://github.com/netbox-community/netbox/issues/11254) - Introduce the `X-Request-ID` HTTP header to annotate the unique ID of each request for change logging
+
 ### Other Changes
 
 * [#10604](https://github.com/netbox-community/netbox/issues/10604) - Remove unused `extra_tabs` block from `object.html` generic template

netbox/netbox/middleware.py

@@ -44,6 +44,9 @@ class CoreMiddleware:
         with change_logging(request):
             response = self.get_response(request)
 
+        # Attach the unique request ID as an HTTP header.
+        response['X-Request-ID'] = request.id
+
         # If this is an API request, attach an HTTP header annotating the API version (e.g. '3.5').
         if is_api_request(request):
             response['API-Version'] = settings.REST_FRAMEWORK_VERSION

netbox/netbox/tests/test_api.py

@@ -1,3 +1,5 @@
+import uuid
+
 from django.urls import reverse
 
 from utilities.testing import APITestCase
@@ -5,14 +7,22 @@ from utilities.testing import APITestCase
 
 class AppTest(APITestCase):
 
+    def test_http_headers(self):
+        response = self.client.get(reverse('api-root'), **self.header)
+
+        # Check that all custom response headers are present and valid
+        self.assertEqual(response.status_code, 200)
+        request_id = response.headers['X-Request-ID']
+        uuid.UUID(request_id)
+
     def test_root(self):
         url = reverse('api-root')
-        response = self.client.get('{}?format=api'.format(url), **self.header)
+        response = self.client.get(f'{url}?format=api', **self.header)
 
         self.assertEqual(response.status_code, 200)
 
     def test_status(self):
         url = reverse('api-status')
-        response = self.client.get('{}?format=api'.format(url), **self.header)
+        response = self.client.get(f'{url}?format=api', **self.header)
 
         self.assertEqual(response.status_code, 200)