Designing gRPC APIs - The things they don't tell you

What if you could evolve gRPC APIs without ever creating a v2? Learn an evergreen strategy for painless, backward-compatible updates.

#1about 2 minutes

Combining resource-oriented design with RPC in gRPC

gRPC uses remote procedure calls, but adopting a resource-oriented design philosophy improves API consistency and predictability.

#2about 5 minutes

Choosing a repository structure for your gRPC project

Evaluate different repository strategies, such as a dedicated proto repo or a monorepo, to manage API definitions and generated code effectively.

#3about 2 minutes

Using linters to enforce API design consistency

Use a linter like Buff to enforce consistent API design rules, but understand the rationale behind warnings to know when they can be safely ignored.

#4about 2 minutes

Understanding the wire format to avoid breaking changes

The gRPC wire format uses integer keys instead of message names, which allows for evolving message types without causing a breaking change for older clients.

#5about 5 minutes

Evolving an API without versioning using a fallback pattern

Instead of versioning, evolve an API by deprecating old methods and adding new ones, while clients use a try-catch fallback to handle older server versions gracefully.

#6about 2 minutes

Handling optional fields and nullable types in Protobuf

Be aware that the `optional` keyword and wrapper types for nullability behave differently across programming languages, affecting client-side code.

#7about 3 minutes

Using the richer error model for detailed error handling

Move beyond simple status codes by using the richer error model to send structured, machine-readable error details in a backward-compatible way.

#8about 2 minutes

Implementing authentication in gRPC services

Leverage existing web framework authentication mechanisms or pre-shared keys, and ensure unauthenticated responses include the correct gRPC headers to be compliant.