What are the best practices for designing gRPC APIs at scale?

gRPC API design best practices: (1) Use resource-oriented design — model APIs around resources (nouns) with standard operations (Get, List, Create, Update, Delete, Search), following Google's AIP (API Improvement Proposals) guidelines; (2) Request/response messages per method — even for simple calls, use distinct request/response types (not primitives) to enable future extension without breaking changes; (3) Pagination — use page_size and page_token fields for list operations; (4) Field masks — use google.protobuf.FieldMask for partial updates and sparse reads; (5) Idempotency keys — include a request_id field for Create operations to enable safe retries; (6) Error handling — use rich error details with google.rpc.Status; (7) Deadline-aware — all handlers should check context cancellation regularly; (8) Break detection — use Buf breaking change detection in CI; (9) Document with comments — .proto comments generate documentation.