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.


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: 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.


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 of resource types include:


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: ""
    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 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}


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