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

Changelog

  • 2019-07-17: Fleshed out the annotation example somewhat.