Best Practice | Request Tracking with x-api-request-id

Introduction

Effective as of Patch 22, CMiC APIs support an optional request tracking mechanism via the x-api-request-id HTTP header. The x-api-request-id HTTP header is used to track a disrupted request made to CMiC due to connectivity issues.

How It Works

The primary objective of the x-api-request-id header is to act as a mechanism to tie together all the database changes or attempted changes (insert/update/delete) related to a single operation (CREATE, UPDATE, and DELETE).

When a single API CREATE request is made to CMiC, CMiC automatically generates a UUID for every request and records it in the database. No action is required on your part for this to occur.

If you anticipate a potential connection drop and want to be able to look up the outcome afterward, you can supply your own request ID in the header before sending the request:

x-api-request-id: 550e8400-e29b-41d4-a716-446655440000 

If network connectivity is not a concern, it is recommended to not send the x-api-request-id header at all. CMiC will handle tracking automatically.

IMPORTANT: Do not reuse an ID from a previous request. CMiC will treat a duplicate ID as a duplicate request and will not process it.

Use Case

Bulk Batch Operations

This functionality is available across all CMiC APIs. However, it is especially designed for batch operations, such as header and detail nested payloads or bulk inserts. For batch APIs, if any record in the batch fails, the entire request is stopped and rolled back. This can create an issue for third party integrators who rely on the completion of the request before receiving a UUID in the successful response.

By supplying a request ID on a supported batch API call, you can query the error detail endpoint afterward to retrieve a structured breakdown of what failed and the reason.

NOTE: Error detail querying is available on Nexus 2 onwards.

Querying Request Outcomes

As of Patch 22, if a request ID is supplied, you can use the following endpoints to look up what happened.

Check request status:

GET /clientrequest?finder=requestId;requestId="<your-request-id>"

Returns whether the request was received and resulted in a success, failure, or partial success.

Retrieve structured error detail — supported batch APIs only (Nexus 2+):

As of Nexus 2 onwards, users can use the clientrequesterrordetails endpoint to retrieve the details of the failed messages, where applicable.

GET /clientrequesterrordetails?finder=searchbyrequestid;requestIds="<your-request-id>" 

Returns a structured error breakdown including a failureMsg and, where applicable, nested errors identifying which specific records failed and why.

Considerations

• The x-api-request-id HTTP header only applies to CREATE, UPDATE, and DELETE operations.
• The x-api-request-id HTTP header is not a record ID and does not replace the UUID CMiC assigns to the data created by the request.
• The x-api-request-id tracks whether the API call succeeded or failed. It does not return the data that was created or modified by that call. To retrieve the actual record, use the relevant API endpoint with the record's own ID.

Summary