AIP-155

Request identification

It is sometimes useful for an API to have a unique, customer-provided identifier for particular requests. This can be useful for several purposes, such as de-duplicating requests from parallel processes, ensuring the safety of retries, or auditing.

The most important purpose for request IDs is to provide idempotency guarantees: allowing the same request to be issued more than once without subsequent calls having any effect. In the event of a network failure, the client can retry the request, and the server can detect duplication and ensure that the request is only processed once.

Guidance

APIs may add a string request_id parameter to request messages (including those of standard methods) in order to uniquely identify particular requests.

message CreateBookRequest {
  // The parent resource where this book will be created.
  // Format: publishers/{publisher}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The ID to use for the book, which will become the final component of
  // the book's resource name.
  //
  // This value should be 4-63 characters, and valid characters
  // are /[a-z][0-9]-/.
  string book_id = 2 [(google.api.field_behavior) = REQUIRED];

  // The book to create.
  Book book = 3 [(google.api.field_behavior) = REQUIRED];

  // A unique identifier for this request. Restricted to 36 ASCII characters.
  // A random UUID is recommended.
  // This request is only idempotent if a `request_id` is provided.
  string request_id = 4 [(google.api.field_info).format = UUID4];
}
  • Providing a request ID must guarantee idempotency.
    • If a duplicate request is detected, the server should return the response for the previously successful request, because the client most likely did not receive the previous response.
    • APIs may choose any reasonable timeframe for honoring request IDs.
  • The request_id field must be provided on the request message to which it applies (and it must not be a field on resources themselves).
  • Request IDs should be optional.
  • Request IDs should be able to be UUIDs, and may allow UUIDs to be the only valid format. The format restrictions for request IDs must be documented.
    • Request IDs that are UUIDs must be annotated with the google.api.FieldInfo.Format value UUID4 using the extension (google.api.field_info).format = UUID4. See AIP-202 for more.

Stale success responses

In some unusual situations, it may not be possible to return an identical success response. For example, a duplicate request to create a resource may arrive after the resource has not only been created, but subsequently updated; because the service has no other need to retain the historical data, it is no longer feasible to return an identical success response.

In this situation, the method may return the current state of the resource instead. In other words, it is permissible to substitute the historical success response with a similar response that reflects more current data.

Further reading

  • For which codes to retry, see AIP-194.
  • For how to retry errors in client libraries, see AIP-4221.

Rationale

Using UUIDs for request identification

When a value is required to be unique, leaving the format open-ended can lead to API consumers incorrectly providing a duplicate identifier. As such, standardizing on a universally unique identifier drastically reduces the chance for collisions when done correctly.

Changelog

  • 2024-01-08: Add book_id to request message.
  • 2023-10-02: Add UUID format extension guidance.
  • 2019-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.