This chapter will discuss how to use Protocol Buffers with API design. To simplify developer experience and improve runtime efficiency, gRPC APIs should use Protocol Buffers version 3 (proto3) for API definition.
Protocol Buffers is a simple language-neutral and platform-neutral Interface Definition Language (IDL) for defining data structure schemas and programming interfaces. It supports both binary and text wire formats, and works with many different wire protocols on different platforms.
Proto3 is the latest version of Protocol Buffers and includes the following changes from proto2:
- Field presence, also known as
hasField, is removed by default for primitive fields. An unset primitive field has a language-defined default value.- Presence of a message field is still available, which can be tested
using the compiler generated
hasFieldmethod, or compare to null, or the sentinel value defined by the implementation. - Beginning in protobuf v3.14, primitive fields can distinguish between
the default value and unset value by using the
optionalkeyword, although this is generally discouraged.
- Presence of a message field is still available, which can be tested
using the compiler generated
- User-defined default value for fields is no longer available.
- Enum definitions must start with enum value zero.
- Required fields are no longer available.
- Extensions are no longer available. Use
google.protobuf.Anyinstead.- Special exception is granted for
google/protobuf/descriptor.protofor backward and runtime compatibility reasons.
- Special exception is granted for
- Group syntax is removed.
The reason for removing these features is to make API designs simpler, more stable, and more performant. For example, it is often necessary to filter some fields before logging a message, such as removing sensitive information. This would not be possible if the fields are required.
See Protocol Buffers for more information.