Google Protobuf Packages

calendarDec 12, 2024 · 6 min read · protobuf google api grpc  ·
Share on: linkedincopy

Useful Google protobuf packages for APIs, gRPC, and common patterns.

googleapis

Common Google API definitions.

Installation

1# Using buf
2buf dep update
3
4# Add to buf.yaml
5deps:
6  - buf.build/googleapis/googleapis

google.type

Common types for APIs.

 1import "google/type/date.proto";
 2import "google/type/datetime.proto";
 3import "google/type/dayofweek.proto";
 4import "google/type/money.proto";
 5import "google/type/postal_address.proto";
 6import "google/type/latlng.proto";
 7import "google/type/color.proto";
 8
 9message Event {
10    string name = 1;
11    google.type.Date start_date = 2;
12    google.type.DateTime start_time = 3;
13    google.type.DayOfWeek day = 4;
14}
15
16message Product {
17    string name = 1;
18    google.type.Money price = 2;
19}
20
21message Location {
22    string name = 1;
23    google.type.LatLng coordinates = 2;
24    google.type.PostalAddress address = 3;
25}

Date

1message Date {
2    int32 year = 1;   // Year (e.g., 2024)
3    int32 month = 2;  // Month (1-12)
4    int32 day = 3;    // Day (1-31)
5}

Money

1message Money {
2    string currency_code = 1;  // ISO 4217 (e.g., "USD")
3    int64 units = 2;           // Whole units
4    int32 nanos = 3;           // Fractional units (nano precision)
5}

Example:

1price := &money.Money{
2    CurrencyCode: "USD",
3    Units: 19,
4    Nanos: 990000000,  // $19.99
5}

LatLng

1message LatLng {
2    double latitude = 1;   // -90 to +90
3    double longitude = 2;  // -180 to +180
4}

google.rpc

Standard RPC error handling.

Status

1import "google/rpc/status.proto";
2import "google/rpc/error_details.proto";
3
4message Response {
5    google.rpc.Status status = 1;
6    bytes data = 2;
7}

Error Details

 1import "google/rpc/error_details.proto";
 2
 3// Common error details
 4google.rpc.RetryInfo
 5google.rpc.DebugInfo
 6google.rpc.QuotaFailure
 7google.rpc.PreconditionFailure
 8google.rpc.BadRequest
 9google.rpc.RequestInfo
10google.rpc.ResourceInfo
11google.rpc.Help
12google.rpc.LocalizedMessage

Usage (Go):

 1import (
 2    "google.golang.org/genproto/googleapis/rpc/errdetails"
 3    "google.golang.org/grpc/codes"
 4    "google.golang.org/grpc/status"
 5)
 6
 7// Create error with details
 8st := status.New(codes.InvalidArgument, "invalid email format")
 9br := &errdetails.BadRequest{
10    FieldViolations: []*errdetails.BadRequest_FieldViolation{
11        {
12            Field: "email",
13            Description: "must be a valid email address",
14        },
15    },
16}
17st, err := st.WithDetails(br)
18return st.Err()

google.api

API annotations for REST/gRPC transcoding.

HTTP Annotations

 1import "google/api/annotations.proto";
 2import "google/api/http.proto";
 3
 4service UserService {
 5    rpc GetUser(GetUserRequest) returns (User) {
 6        option (google.api.http) = {
 7            get: "/v1/users/{user_id}"
 8        };
 9    }
10    
11    rpc CreateUser(CreateUserRequest) returns (User) {
12        option (google.api.http) = {
13            post: "/v1/users"
14            body: "*"
15        };
16    }
17    
18    rpc UpdateUser(UpdateUserRequest) returns (User) {
19        option (google.api.http) = {
20            patch: "/v1/users/{user.id}"
21            body: "user"
22        };
23    }
24    
25    rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
26        option (google.api.http) = {
27            delete: "/v1/users/{user_id}"
28        };
29    }
30    
31    rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
32        option (google.api.http) = {
33            get: "/v1/users"
34        };
35    }
36}

Field Behavior

1import "google/api/field_behavior.proto";
2
3message CreateUserRequest {
4    string name = 1 [(google.api.field_behavior) = REQUIRED];
5    string email = 2 [(google.api.field_behavior) = REQUIRED];
6    string phone = 3 [(google.api.field_behavior) = OPTIONAL];
7    string id = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
8}

Field Behaviors:

  • REQUIRED - Must be provided
  • OPTIONAL - May be provided
  • OUTPUT_ONLY - Read-only, set by server
  • INPUT_ONLY - Write-only, not returned
  • IMMUTABLE - Cannot be changed after creation

Resource

 1import "google/api/resource.proto";
 2
 3message User {
 4    option (google.api.resource) = {
 5        type: "example.com/User"
 6        pattern: "users/{user}"
 7    };
 8    
 9    string name = 1;
10}
11
12message GetUserRequest {
13    string name = 1 [(google.api.resource_reference) = {
14        type: "example.com/User"
15    }];
16}

google.longrunning

Long-running operations.

 1import "google/longrunning/operations.proto";
 2
 3service BatchService {
 4    rpc ProcessBatch(ProcessBatchRequest) returns (google.longrunning.Operation) {
 5        option (google.api.http) = {
 6            post: "/v1/batches:process"
 7            body: "*"
 8        };
 9        option (google.longrunning.operation_info) = {
10            response_type: "ProcessBatchResponse"
11            metadata_type: "ProcessBatchMetadata"
12        };
13    }
14}
15
16message ProcessBatchMetadata {
17    int32 total_items = 1;
18    int32 processed_items = 2;
19    google.protobuf.Timestamp start_time = 3;
20}
21
22message ProcessBatchResponse {
23    int32 successful = 1;
24    int32 failed = 2;
25    repeated string errors = 3;
26}

Usage (Go):

 1import (
 2    "google.golang.org/genproto/googleapis/longrunning"
 3)
 4
 5// Start operation
 6op, err := client.ProcessBatch(ctx, req)
 7
 8// Poll for completion
 9for {
10    if op.Done {
11        if err := op.GetError(); err != nil {
12            // handle error
13        }
14        resp := &ProcessBatchResponse{}
15        op.GetResponse().UnmarshalTo(resp)
16        break
17    }
18    time.Sleep(time.Second)
19    op, _ = opsClient.GetOperation(ctx, &longrunning.GetOperationRequest{
20        Name: op.Name,
21    })
22}

buf.build Packages

buf.validate

Validation rules for fields.

 1import "buf/validate/validate.proto";
 2
 3message User {
 4    string email = 1 [(buf.validate.field).string = {
 5        email: true
 6        min_len: 5
 7        max_len: 100
 8    }];
 9    
10    int32 age = 2 [(buf.validate.field).int32 = {
11        gte: 0
12        lte: 150
13    }];
14    
15    string username = 3 [(buf.validate.field).string = {
16        pattern: "^[a-z0-9_]{3,20}$"
17    }];
18    
19    repeated string tags = 4 [(buf.validate.field).repeated = {
20        min_items: 1
21        max_items: 10
22        items: {
23            string: {
24                min_len: 1
25                max_len: 50
26            }
27        }
28    }];
29}

envoyproxy/protoc-gen-validate

Alternative validation (older, still widely used).

1import "validate/validate.proto";
2
3message User {
4    string email = 1 [(validate.rules).string.email = true];
5    int32 age = 2 [(validate.rules).int32 = {gte: 0, lte: 150}];
6    string uuid = 3 [(validate.rules).string.uuid = true];
7}

grpc-ecosystem

grpc-gateway

REST to gRPC transcoding.

 1import "protoc-gen-openapiv2/options/annotations.proto";
 2
 3option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 4    info: {
 5        title: "User API";
 6        version: "1.0";
 7        description: "User management API";
 8    };
 9    schemes: HTTPS;
10    consumes: "application/json";
11    produces: "application/json";
12};
13
14service UserService {
15    rpc GetUser(GetUserRequest) returns (User) {
16        option (google.api.http) = {
17            get: "/v1/users/{user_id}"
18        };
19        option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
20            summary: "Get user by ID"
21            description: "Returns a single user"
22            tags: "Users"
23        };
24    }
25}

Quick Reference

PackageImportUse Case
google.typegoogle/type/*.protoCommon types (Date, Money, LatLng)
google.rpcgoogle/rpc/*.protoError handling, status codes
google.apigoogle/api/*.protoREST annotations, field behavior
google.longrunninggoogle/longrunning/*.protoLong-running operations
buf.validatebuf/validate/validate.protoField validation rules
grpc-gatewayprotoc-gen-openapiv2/options/*.protoOpenAPI/Swagger docs

buf.yaml Example

 1version: v1
 2deps:
 3  - buf.build/googleapis/googleapis
 4  - buf.build/bufbuild/protovalidate
 5  - buf.build/grpc-ecosystem/grpc-gateway
 6lint:
 7  use:
 8    - DEFAULT
 9breaking:
10  use:
11    - FILE

Best Practices

  1. Use google.type.Money - Don't use float/double for money
  2. Use google.type.Date - Separate date from time when appropriate
  3. Use google.api.http - Enable REST/gRPC transcoding
  4. Use google.api.field_behavior - Document field requirements
  5. Use google.rpc.Status - Standard error responses
  6. Use validation - buf.validate or protoc-gen-validate
  7. Use google.longrunning.Operation - For async operations

Common Imports

 1syntax = "proto3";
 2
 3package myapp.v1;
 4
 5// Well-known types
 6import "google/protobuf/timestamp.proto";
 7import "google/protobuf/duration.proto";
 8import "google/protobuf/empty.proto";
 9import "google/protobuf/field_mask.proto";
10
11// Google types
12import "google/type/date.proto";
13import "google/type/money.proto";
14import "google/type/latlng.proto";
15
16// API annotations
17import "google/api/annotations.proto";
18import "google/api/field_behavior.proto";
19import "google/api/resource.proto";
20
21// Validation
22import "buf/validate/validate.proto";

Related Snippets