Master API Resource Naming: Best Practices for Consistent Backend Design

Guidance

All resource names defined by an API must be unique within that API. Resource names are formatted according to the URI path pattern without a leading slash:

publishers/123/books/les-miserables
users/vhugo1802

Resource name components should alternate between a collection identifier (e.g., publishers, books, users) and a resource ID (e.g., 123, les-miserables, vhugo1802).

Resource names must use the '/' character to separate parts.

Resource names should only use characters allowed by RFC‑1123 DNS names.

Resources must expose a name field.

Collection Identifiers

Collection identifier parts must be plural, use concise American English terms, be in camelCase, start with a lowercase letter, contain only ASCII letters and digits, and be plural.

Plural form must be correct; do not create new words by simply adding “s” when inappropriate.

Nested Collections

If a resource name contains multiple hierarchical levels, the child collection may omit the parent prefix. Example: users/vhugo1802/userEvents/birthday-dinner-226 The API should use a less redundant form: users/vhugo1802/events/birthday-dinner-226 In this case the message is still called UserEvent, but the resource name is shortened.

Resource ID Part

The resource ID part identifies the resource within its parent collection. IDs can be user‑specified, optionally user‑specified, or never user‑specified, and must be immutable once created.

User‑specified IDs must match the regex ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

IDs should not use characters outside ASCII; if Unicode is required, follow AIP‑210.

IDs must not be UUIDs.

If user‑specified, the API must document the allowed format, which should conform to RPC‑1034 (letters, digits, hyphens, start with a letter, end with a letter or digit, max 63 characters).

If not user‑specified, the API should document the basic format and any limits.

Resource ID Aliases

APIs may provide alias paths for common lookup patterns, such as users/me, but all returned data must use the canonical resource name.

Fully Qualified Resource Names

When a service needs to reference a resource across APIs, it should use a fully qualified resource name consisting of the service endpoint without a scheme followed by the relative resource name.

//library.googleapis.com/publishers/123/books/les-miserables
//calendar.googleapis.com/users/vhugo1802

Fully qualified names should not be used for cross‑API references that have a clearly defined owning API.

Resource URIs

Full resource names are scheme‑less URIs; the full URI used to access a resource adds HTTPS and an API version.

https://library.googleapis.com/v1/publishers/123/books/les-miserables
https://calendar.googleapis.com/v3/users/vhugo1802

The version is omitted from the fully qualified name because it is expected to remain stable across versions.

Fields Representing Resource Names

The first field of a resource definition should be a string named name and annotated with google.api.resource_reference referencing the resource type (AIP‑123).

// Book message example
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };
  string name = 1;
  // other fields...
}

Request messages for methods that act on existing resources should also have a name field with the same requirements.

// ArchiveBook request
message ArchiveBookRequest {
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/Book"
    }];
  // other fields...
}

Fields Representing Parent Resources

When defining methods that list or create resources, the first field should be a string named parent annotated with google.api.resource_reference referencing the parent resource type.

// ListBooks request
message ListBooksRequest {
  string parent = 1 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Publisher"
  }];
  // other fields...
}

If multiple parent types are possible, the parent field should use the child_type key in the annotation.

// ListBooks request with multiple parents
message ListBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];
  // other fields...
}

Fields Representing Another Resource

Fields that reference a different resource should be strings named after the referenced message in snake_case, optionally with a leading adjective, and annotated with google.api.resource_reference indicating the target type.

// Book message with shelf reference
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };
  string name = 1;
  string shelf = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Shelf"
  }];
}