AIP-123

Resource types

Most APIs expose resources (their primary nouns) which users are able to create, retrieve, and manipulate. APIs are allowed to name their resource types as they see fit, and are only required to ensure uniqueness within that API. This means that it is possible (and often desirable) for different APIs to use the same type name. For example, a Memcache and Redis API would both want to use Instance as a type name.

When mapping the relationships between APIs and their resources, however, it becomes important to have a single, globally-unique type name. Additionally, tools such as Kubernetes or GraphQL interact with APIs from multiple providers.

Terminology

In the guidance below, we use the following terms:

• Service Name: This is the name defined in the service configuration. This usually (but not necessarily) matches the hostname that users use to call the service. Example: pubsub.googleapis.com. This is equivalent to an API Group in Kubernetes.
• Type: This is the name used for the type within the API. This usually (but not necessarily) matches the name of the protobuf message. This is equivalent to an Object in Kubernetes.

Guidance

APIs must define a resource type for each resource in the API, according to the following pattern: {Service Name}/{Type}. The type name must be singular and use PascalCase (UpperCamelCase).

Examples

Examples of resource types include:

• pubsub.googleapis.com/Topic
• pubsub.googleapis.com/Subscription
• spanner.googleapis.com/Database
• spanner.googleapis.com/Instance
• networking.istio.io/Instance

Annotating resource types

APIs should annotate the resource types for each resource in the API using the google.api.resource annotation:

// A representation of a Pub/Sub topic.
message Topic {
  option (google.api.resource) = {
    type: "pubsub.googleapis.com/Topic"
    pattern: "projects/{project}/topics/{topic}"
  };

  // The resource name of the topic.
  string name = 1;

  // Other fields...
}

• Patterns must correspond to the resource name.
• Pattern variables (the segments within braces) must use snake_case, and must not use an _id suffix.
• Pattern variables must be the singular form of the resource type e.g. the pattern variable representing a Topic resource ID is named {topic}.
• Pattern variables must conform to the format [a-z][_a-z0-9]*[a-z0-9].

Pattern uniqueness

When multiple patterns are defined within a resource, these patterns must be mutually unique, where uniqueness is defined as being by-character identical once all resource ID path segments have been removed, leaving all / separators.

Therefore the following two patterns must not be defined within the same resource:

• user/{user}
• user/{user_part_1}~{user_part_2}

Changelog

• 2022-10-28: Added pattern variable format guidance.
• 2020-05-14: Added pattern uniqueness.
• 2019-12-05: Added guidance on patterns.
• 2019-07-17: Fleshed out the annotation example somewhat.