# API Design Conventions — gRPC

Source: https://www.skillbyai.com/en/grpc/o-design

> Consistent, evolvable services.

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

```protobuf
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.

**Quiz:** What does a FieldMask in an update request specify?

- [x] Which fields of the resource should be changed
- [ ] The encryption key
- [ ] The page size
- [ ] The server address

*Answer:* Which fields of the resource should be changed. Partial updates without ambiguity.