Skip to main content

gRPC

gRPC naming follows the Protocol Buffers Style Guide. These are the conventions that matter most in practice.

Packages​

Use lowercase.dot.separated, mirroring your domain and version:

package acmeco.retail.orders.v1;

Always include a version segment. Changing a package name is a breaking change.

Services​

Service names are PascalCase noun phrases:

service OrderService { }
service UserService { }
service PaymentProcessor { }

Methods​

Method names are PascalCase verbs. Follow the standard CRUD pattern where it fits:

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
}

Messages​

Message names are PascalCase. Request and response messages are named after their method:

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  User user = 1;
}

message User {
  string id = 1;
  string first_name = 2;
  string last_name = 3;
  string email_address = 4;
  google.protobuf.Timestamp created_at = 5;
}

Fields​

Message fields use snake_case — this is a proto3 requirement, not a style choice. The generated code will adapt to the target language's conventions automatically.

Enums​

Enum type names are PascalCase. Enum value names are SCREAMING_SNAKE_CASE and are prefixed with the enum name to avoid collisions across the package:

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_FULFILLED = 2;
  ORDER_STATUS_CANCELLED = 3;
}

Always include an _UNSPECIFIED = 0 value. It serves as the default and makes unset fields detectable.