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 reasonably freely (within the requirements of this AIP), 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 e.g. 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:

• Match the containing API type's name.
• Start with an uppercase letter.
• Only contain alphanumeric characters.
• Be of the singular form of the noun.
• 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}"
    singular: "topic"
    plural: "topics"
  };

  // Name and 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 conform to the format [a-z][_a-z0-9]*[a-z0-9].
• Pattern variables must be unique within any given pattern. (e.g. projects/{abc}/topics/{abc} is invalid; this is usually a natural corollary of collection identifiers being unique within a pattern.)
• Resources with multiple patterns