API Design Conventions

Resource-oriented methods

Google's API Improvement Proposals (AIPs) describe widely adopted conventions: resource-oriented standard methods (Get, List, Create, Update, Delete) plus custom methods, pagination with page_size and page_token, partial updates with FieldMask, consistent naming (snake_case fields, PascalCase messages and methods), versioned packages (shop.v1) and well-documented fields. Enforce conventions with buf lint and block incompatible changes with buf breaking in CI.

A paginated List method

Following common AIP-style conventions.

import "google/protobuf/field_mask.proto";

service ProductService {
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
  rpc UpdateProduct(UpdateProductRequest) returns (Product);
}

message ListProductsRequest {
  int32 page_size = 1;       // server enforces a maximum
  string page_token = 2;     // opaque token from the previous response
  string filter = 3;
}

message ListProductsResponse {
  repeated Product products = 1;
  string next_page_token = 2;  // empty when there are no more pages
}

message UpdateProductRequest {
  Product product = 1;
  google.protobuf.FieldMask update_mask = 2;   // which fields to change
}

Run buf breaking in CI

Comparing against the main branch blocks accidental wire-incompatible changes before they ship.

Quick check: What does a FieldMask in an update request specify?

• Which fields of the resource should be changed
• The encryption key
• The page size
• The server address