AIP Protocol Buffers & API Design Skill

This skill summarizes Google API Improvement Proposals (AIPs) for designing
and working with protocol buffers, RPCs, services, messages, fields, and
naming for APIs that follow resource-oriented design.

Scope: General AIP guidance from the
google.aip.dev codebase (AIPs in approved state).
Domain-specific AIPs (Cloud, Firebase, Auth, etc.) may add further rules.

Bundled references

• references/full-example.md: Read when implementing a new service or checking request/response shape for standard methods.
• references/naming-and-methods.md: Read when checking naming conventions or RPC/method patterns for standard methods.

---

1. Protocol Buffers (Protos)

1.1 Package and file structure

• Package: Each API must live in a single package that ends in a
  major version (e.g. google.library.v1). Directory layout must match
  the package (e.g. google/library/v1).
• Syntax: Use proto3 only.
• File names: Use snake_case. Avoid language keywords (e.g. not
  import.proto). Must not use the version as the filename (e.g. no
  v1.proto).
• File layout order: Syntax → package → imports (alphabetical) → file
  options → services (standard methods before custom, grouped by resource) →
  resource messages (parent before child) → request/response messages (matching
  RPC order, request before response) → other messages → top-level enums.

1.2 API-specific vs common protos

• API-specific protos belong in the versioned package (e.g.
  google.library.v1). Do not create shared "API-specific common" packages
  across versions; duplicate the proto per version if needed.
• Cross-API references: Use resource names (strings), not the resource
  message type from another API.
• Common components: APIs may import:
  • google.api.* (not subpackages)
  • google.longrunning.Operation
  • google.protobuf.* (e.g. Timestamp, Duration, Struct, FieldMask,
    Empty)
  • google.rpc.*
  • google.type.* (e.g. Date, Money, LatLng, PostalAddress,
    TimeOfDay)
  • google.iam.v1.* where relevant
• Organization-specific common packages must end with .type (e.g.
  google.geo.type), be published in the googleapis repo, and follow AIP-213;
  do not put generic types there.

---

2. Services (interfaces)

• Interface name: Use an intuitive noun in PascalCase (e.g. Library,
  Calendar, BlobStore). Avoid names that clash with common language/runtime
  concepts (e.g. File). If needed, add a suffix like Api or Service to
  disambiguate.
• Methods: Prefer standard methods (Get, List, Create, Update, Delete)
  over custom methods. Group RPCs by resource; list standard methods before
  custom ones.

---

3. Resources and resource names

3.1 Resource-oriented design

• Model the API as a resource hierarchy: resources (nouns) and collections;
  use a small set of standard methods plus custom methods when
  necessary.
• Each resource must support Get. All
  non-singleton resources must support
  List.
• Resource schema (message shape) for a given resource must be the same
  across all methods that take or return that resource.
• Relationships must form a directed acyclic graph; each resource has at
  most one canonical parent. Use parent for collection scope and optional
  filter for other associations (AIP-124, AIP-160).

3.2 Resource names

• Format: Path-like, without leading slash:
  publishers/123/books/les-miserables. Use / only as segment separator;
  no / inside a segment.
• Segments: Alternate collection identifiers (plural, camelCase, e.g.
  publishers, books) and resource ID segments. Collection IDs must be
  unique within a single resource name (no people/xyz/people/abc).
• Characters: Prefer DNS-safe (RFC 1123); avoid uppercase in IDs; avoid
  URL-encoding; if Unicode is needed, use NFC (AIP-210).
• User-specified IDs: Document format; prefer lowercase letters, numbers,
  hyphen; first character letter, last letter or number; max 63 chars (RFC 1034
  style). Duplicate name → ALREADY_EXISTS (or PERMISSION_DENIED if user
  cannot see the duplicate).
• Full resource name (cross-API): schemeless URI with service name +
  relative name, e.g.
  //library.googleapis.com/publishers/123/books/les-miserables.

3.3 Resource types and annotations

• Resource type: {ServiceName}/{Type} (e.g.
  library.googleapis.com/Book). Type must match the message name, singular,
  PascalCase, alphanumeric.
• Annotation: Use google.api.resource with type, pattern, singular,
  plural. Pattern variables: snake_case, no _id suffix, unique within
  pattern. Pattern variables match singular resource type (e.g. {topic} for
  Topic).
• Nested collections: Child collection segment may drop redundant prefix
  (e.g. users/{user}/events/{event} instead of userEvents in path);
  message/type name stays e.g. UserEvent; singular/plural not shortened.

3.4 Fields for resource names

• On the resource message: First field should be string name with
  resource name; annotate with (google.api.field_behavior) = IDENTIFIER and
  google.api.resource.
• In request messages (acting on one resource): Use string name for the
  resource; annotate with REQUIRED and google.api.resource_reference
  (type or child_type). Comment should document the pattern (e.g.
  Format: publishers/{publisher}/books/{book}).
• In request messages (collection scope): Use string parent for the
  collection's parent resource; same annotations and pattern comment.
• Referencing another resource: Prefer string with resource name; field
  name ≈ referenced type in snake_case (e.g. shelf); use
  google.api.resource_reference. Do not embed the other resource's
  message type (except internal/revisions cases in AIP-162). Use _name suffix
  only if needed to avoid ambiguity (e.g. crypto_key_name).
• Reserved: Use name only for resource name; use parent only for parent
  collection. For other concepts use a different name or adjective (e.g.
  display_name).

---

4. RPCs (methods)

4.1 HTTP and transcoding

• Every RPC must have an HTTP mapping via google.api.http (except
  bi-directional streaming, which should have a non-streaming alternative if
  possible).
• Verbs: Use get, post, patch, or delete as prescribed; should
  not use put or custom.
• URI: Use {field=path/*} for variables; use * for one segment (no
  /), ** only if needed for path segments. For Update, use nested field in
  path (e.g. {book.name=...}).
• Body: No body for GET/DELETE. For Create/Update, body must point to
  the resource field; must not be nested, a URI param, or repeated. Prefer not
  using json_name except for compatibility.
• Method signatures: Use google.api.method_signature as specified per
  method type below.

4.2 Standard methods

See references/naming-and-methods.md for the standard-methods table.

• Get: Request has name (required, resource reference). URI single
  variable for resource; method_signature = "name". Response is the resource
  (fully populated unless partial response per AIP-157).
• List: Request has parent (required when not top-level), page_size
  (int32), page_token (string); optional filter, order_by. Response has
  repeated resource field + next_page_token; optional total_size.
  Pagination is mandatory from the start (AIP-158).
  method_signature = "parent" (or "" for top-level).
• Create: Request has parent, {resource}_id, and resource field (body).
  Resource name ignored on input. method_signature = "parent,book,book_id"
  (or without _id if optional). Management plane must allow
  user-specified ID; data plane should.
• Update: Request has resource field (with name) +
  google.protobuf.FieldMask update_mask. URI uses {resource.name=...}.
  Support partial update (PATCH). Omitted mask = all populated fields. Support
  * for full replacement with documented caveats. State fields must not
  be writable in Update (use custom methods). Optional allow_missing for
  upsert when using client-assigned names.
• Delete: Request has name. Optional force for cascading delete;
  optional etag for conditional delete; optional allow_missing for no-op
  when missing. Child resources present without force →
  FAILED_PRECONDITION.

4.3 Custom methods

• Use only when standard methods do not fit; prefer standard methods.
• Name: Verb + noun, UpperCamelCase (e.g. ArchiveBook). Must not
  include prepositions or "Async"; may use LongRunning suffix. Should
  not reuse standard verbs (Get, List, Create, Update, Delete).
• HTTP: GET for read-only; POST for side effects. URI must include
  :customVerb in camelCase (e.g. :archive).
• Body: Prefer body: "*".
• Request/response: {RpcName}Request and {RpcName}Response (or return
  the resource when operating on one resource).
• Resource-based: Single resource → name in path. Collection-based →
  parent in path + literal collection segment. Stateless → scope field (e.g.
  project) in path; verb after : (e.g. :translateText).

4.4 Long-running operations (LRO)

• For operations that take significant time, return
  google.longrunning.Operation with google.longrunning.operation_info
  (response_type, metadata_type). Implement the standard Operations
  service; do not define a custom LRO interface.

---

5. Messages

• Names: Short, PascalCase; no prepositions (e.g. "With", "For"). Omit
  redundant adjectives if there is no contrasting type.
• Request/response: Request = RPC name + Request; response = resource for
  Get/Create/Update (and some custom), or ListXResponse for List, or
  XResponse for custom. Response usually holds the full resource unless
  partial response (AIP-157).
• Conflict: A message should not have a field with the same name as the
  message (after case normalization).

---

6. Fields

6.1 Field names (AIP-140)

• Case: lower_snake_case in proto. No leading/trailing/adjacent
  underscores; no word starting with a number.
• Language: Correct American English; same concept = same name across APIs;
  avoid overloaded or overly generic names (e.g. "instance", "info", "service"
  only with clear context).
• Repeated: Use plural (books); non-repeated use singular (book).
  Resource names in field names use singular.
• Prepositions: Avoid ("for", "with", "at", "by"); e.g. error_reason not
  reason_for_error. "Per" is allowed in units (AIP-141).
• Abbreviations: Use common ones: config, id, info, spec, stats;
  for units use common abbreviations (e.g. _km, _px).
• Adjective + noun: Adjective before noun: collected_items not
  items_collected.
• Verbs: Field names must not be verbs or intent/action; use nouns
  (current or desired value).
• Booleans: Omit is_ prefix: disabled not is_disabled (exception:
  reserved words, e.g. is_new).
• URIs: Prefer uri; if only URLs, use url. Optional prefix (e.g.
  image_url).
• Display: Human-readable name → display_name (no uniqueness).
  Formal/official name → title (no uniqueness).
• Reserved words: Avoid names that conflict with common language keywords.

6.2 Field behavior (AIP-203)

• Must apply google.api.field_behavior on every field of messages used in
  requests. Use at least one of: REQUIRED, OPTIONAL, OUTPUT_ONLY. Never
  use FIELD_BEHAVIOR_UNSPECIFIED.
• IDENTIFIER: Only on the resource's name field (identifies resource; not
  input on Create; immutable on Update).
• REQUIRED / OPTIONAL: For input fields; required = must be present and
  non-empty where applicable.
• OUTPUT_ONLY: Response-only; server clears on input; ignore in
  update_mask.
• INPUT_ONLY: Request-only; not in response (rare; e.g. some TTL patterns).
• IMMUTABLE: Cannot be changed after creation; ignore if unchanged on
  update, error if change requested.
• UNORDERED_LIST: Repeated field order not guaranteed.

6.3 Standard and special fields

• Timestamps: Use google.protobuf.Timestamp; names end in _time (e.g.
  create_time, update_time). Use imperative form: publish_time not
  published_time (AIP-142).
• Durations: Use google.protobuf.Duration; e.g. flight_duration
  (AIP-142).
• State: Use enum State (or XxxState) nested in the resource; values
  like ACTIVE, SUCCEEDED, FAILED, CREATING, DELETING. Field
  should be output-only; state changes via custom methods, not Update
  (AIP-216).
• Enums: Values in UPPER_SNAKE_CASE; first value {Enum}_UNSPECIFIED (or
  UNKNOWN if zero). Nested in message when used only there (AIP-126).
• Quantities: Include unit suffix (e.g. distance_km, node_count); use
  _count for counts, not num_ (AIP-141). No unsigned integers.
• Etag: Optional string etag for optimistic concurrency; mismatch on
  update/delete → ABORTED.
• Format / FieldInfo: Use google.api.field_info format (e.g. UUID4, IPv4,
  IPv6) only when specified by an AIP; document and compare per spec (AIP-202).

6.4 Pagination (List)

• Request: int32 page_size (optional; document default and max; coerce over
  max; error on negative), string page_token.
• Response: repeated items + string next_page_token (set only when there is a
  next page).

---

7. Naming summary

See references/naming-and-methods.md for the naming summary table.

---

8. Errors and documentation

• Errors: Return google.rpc.Status with google.rpc.Code. Include
  ErrorInfo in details with machine-readable reason (UPPER_SNAKE_CASE,
  ≤63 chars). Message: developer-facing, English, brief and actionable; dynamic
  parts in details.
• Comments: Every message, RPC, and field should have a clear comment
  (valid American English). Document resource name patterns (Format: ...) and
  constraints (e.g. page_size default/max).
• Precedent violations: If deviating from AIP guidance, document with
  comment prefixed aip.dev/not-precedent and justify per AIP-200.

---

9. Best practices (concise)

1. Run the API Linter and fix
   reported issues (or document why a rule is disabled).
2. Keep APIs self-contained: versioned package, resource names for cross-API
   refs, shared types only from approved common packages.
3. Use standard methods and standard request/response shapes; add custom
   methods only when necessary.
4. Annotate all request fields with field_behavior; annotate resource and
   reference fields with google.api.resource / resource_reference.
5. Use consistent vocabulary: same concept → same name; avoid overloaded terms;
   prefer standard fields (name, parent, create_time, update_time,
   display_name, etag, state).
6. Design for many clients: CLIs, SDKs, declarative/IaC, UIs; avoid
   special-casing that hurts one client for marginal gain.
7. Preserve backwards compatibility: no breaking changes to field behavior,
   required fields, or resource names within a major version; pagination and
   LRO from day one where applicable.

---

10. Example (minimal CRUD resource)

For a full minimal CRUD proto example (service, Book resource, and all request/response messages), see references/full-example.md.

---

11. References

• AIP index: google.aip.dev
• API Linter:
  github.com/googleapis/api-linter
• Key AIPs: 1 (purpose), 8 (style), 121 (resource design), 122 (resource
  names), 123 (resource types), 127 (HTTP transcoding), 131–136 (standard +
  custom methods), 140 (field names), 158 (pagination), 190 (naming), 203
  (field behavior), 213/215 (common/API-specific protos)

When in doubt, open the specific AIP on
google.aip.dev for full guidance and rationale.