> Markdown version of [/videos/689-designing-grpc-apis-the-things-they-don-t-tell-you](https://www.wearedevelopers.com/videos/689-designing-grpc-apis-the-things-they-don-t-tell-you). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

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

Did you know gRPC's language-agnostic promise often breaks down at the implementation layer? Uncover the hidden architectural truths behind evergreen versioning, nullability, and robust error handling.

- **Speakers:** Bastian Eicher
- **Event:** World Congress 2023
- **Published:** September 27, 2023
- **Duration:** 27:17
- **URL:** https://www.wearedevelopers.com/videos/689-designing-grpc-apis-the-things-they-don-t-tell-you

## Summary

While gRPC offers substantial benefits through API-first design, code generation, and binary encoding performance, successfully implementing it requires navigating architectural nuances often glossed over in standard documentation. Although inherently based on remote procedure calls, blending gRPC with resource-oriented principles yields more symmetrical and predictable interfaces. Establishing a clear repository structure upfront—such as utilizing monorepos or dedicated protocol buffer repositories—prevents synchronization headaches across language barriers and streamlines cross-cutting references, which strictly forbid cyclic dependencies.\n\nDesigning evolvable APIs means understanding the distinction between compile-time breaking changes and wire-format breaking changes. Because the gRPC wire format relies on integer tags rather than message names, developers can radically alter inputs and outputs safely if field IDs remain consistent. This flexibility enables an evergreen versioning approach: instead of duplicating code for strict V1 and V2 interfaces, clients can utilize a graceful fallback pattern, attempting a new method and catching an unimplemented exception to seamlessly revert to legacy behavior. To enforce consistency across these evolutions, adopting a dedicated linter like Buf is highly recommended, though strict rules—such as requiring unique request and response objects per method—should be weighed against immediate code readability.\n\nThe promise of purely language-agnostic design often breaks down at the implementation layer, particularly concerning nullability, as protobuf strings default to empty rather than null, and wrapper types exhibit drastically different behaviors across languages like C# and Python. For robust operations, adopting Google's Richer Error Model allows developers to attach arbitrary, machine-readable protobuf messages to error headers, avoiding the constraints of default status codes. Similarly, rather than immediately reaching for complex mutual TLS configurations, implementing pre-shared secrets via lower-level HTTP headers provides a pragmatic, secure authentication layer that bypasses heavy infrastructure requirements.

**Keywords:** gRPC API design, protocol buffers wire format, resource-oriented API patterns, monorepo protocol management, API versioning strategies, gRPC backward compatibility, buf protocol linter, wire-format breaking changes, graceful API fallback pattern, protobuf nullability semantics, gRPC richer error model, machine-readable API errors, HTTP header authentication, pre-shared secret auth, cross-language code generation, protobuf nested messages

## Chapters

1. **Motivation for using gRPC APIs over RESTful JSON** (00:01) — Performance and robust code generation make API-first design approaches preferable to traditional JSON payloads.
1. **Blending resource-oriented and RPC philosophies in API design** (01:11) — Applying resource-oriented CRUD concepts within remote procedure call architectures offers functional symmetry and predictable implementation.
1. **Structuring git repositories to share remote procedure contracts** (02:07) — Choosing the right dedicated or monorepo structure dictates how service boundaries securely share client libraries.
1. **Resolving cyclic dependencies within identity management protocol buffers** (04:22) — Organizing cross-cutting references strictly on primary domain entities circumvents cyclic import errors during compilation.
1. **Enforcing API consistency using the Buf protobuf linter** (06:33) — Evaluating warning rules around separated request objects guarantees long-term evolvability across diverse client constraints.
1. **Understanding breaking changes within the binary wire format** (08:45) — Keeping message integer references unchanged enables structural backward compatibility over binary encoded TCP connections.
1. **Leveraging fallback behaviors to avoid complex API versioning** (11:05) — Safely conditionally executing newer remote methods inside try-catch patterns handles mixed upgrade environments without duplicate definitions.
1. **Handling optional fields and language-specific nullability discrepancies** (16:06) — Relying on explicit wrapper types normalizes the erratic missing-value semantics found between C# and Python generators.
1. **Structuring exceptions using the gRPC rich error model** (18:18) — Attaching detailed machine-readable precondition records directly into unhandled exceptions bypasses the rigidity of standard status codes.
1. **Implementing low-level authentication headers for service-to-service communication** (21:35) — Injecting preshared keys directly into HTTP header payloads acts as a lightweight alternative to mutual TLS integrations.
1. **Strongly typed nested models and generated code quality** (24:46) — Exploring how granularly defining internal typed properties improves maintainability despite lack of native web proxy support.

## Related Moments

- [Choosing the right API protocol today](https://www.wearedevelopers.com/videos/1683-rest-in-peace-what-does-the-api-protocol-of-the-future-look-like-or-do-we-have-it-already) (from "REST in Peace? What does the API protocol of the future look like? Or do we have it already?")
- [Evaluating architectural trade-offs between REST and gRPC](https://www.wearedevelopers.com/videos/1935-boosting-opensearch-performance-grpc-search-in-action) (from "Boosting OpenSearch Performance: gRPC Search in Action")
- [Architectural mapping of resources across different API protocols](https://www.wearedevelopers.com/videos/1195-the-great-api-debate-rest-graphql-or-grpc) (from "The Great API Debate: REST, GraphQL, or gRPC?")
- [Establishing internal service communication with gRPC](https://www.wearedevelopers.com/videos/100247-rest-graphql-grpc-and-more-a-comparison-of-modern-api-styles) (from "REST, GraphQL, gRPC, and more: A comparison of modern API styles")
- [High performance communication protocols using gRPC](https://www.wearedevelopers.com/videos/1683-rest-in-peace-what-does-the-api-protocol-of-the-future-look-like-or-do-we-have-it-already) (from "REST in Peace? What does the API protocol of the future look like? Or do we have it already?")
- [Limitations and browser support challenges in gRPC](https://www.wearedevelopers.com/videos/1576-grpc-load-balancing-deep-dive) (from "gRPC Load Balancing Deep Dive")

## Related Articles

- [Dev Digest 139 - Soft and hard queries](https://www.wearedevelopers.com/magazine/487-dev-digest-139-soft-and-hard-queries)
- [Douglas Crockford - JSON and Beyond](https://www.wearedevelopers.com/magazine/481-douglas-crockford-json-and-beyond)
- [Dev Digest 129 - Now that's what I call private data!](https://www.wearedevelopers.com/magazine/468-dev-digest-129-now-that-s-what-i-call-private-data)
- [How to Avoid Over-Engineering](https://www.wearedevelopers.com/magazine/546-how-to-avoid-over-engineering)

## Related Jobs

- [Senior Backend Developer — AI: MCP & Agent Engine](https://www.wearedevelopers.com/jobs/48297-senior-backend-developer-ai-mcp-agent-engine) at **basebox GmbH**
- [Staff Software Engineer](https://www.wearedevelopers.com/jobs/ext/1425755-staff-software-engineer) at **GitHub**
- [Principal Software Engineer, Database Infrastructure](https://www.wearedevelopers.com/jobs/ext/1465908-principal-software-engineer-database-infrastructure) at **GitHub**
- [Senior Software Engineer, Client Apps Platform](https://www.wearedevelopers.com/jobs/ext/1773893-senior-software-engineer-client-apps-platform) at **GitHub**
- [Senior Backend Engineer (Java)](https://www.wearedevelopers.com/jobs/ext/19369-senior-backend-engineer-java) at **Bonial International GmbH**
- [Principal Software Engineer, Identity](https://www.wearedevelopers.com/jobs/ext/1469181-principal-software-engineer-identity) at **GitHub**