api

The wire-format module. Source: api/.

Purpose

go.etcd.io/etcd/api/v3 defines every protobuf message and gRPC service the cluster speaks. It is intentionally small in dependency footprint — both the server and the official client import it, and external clients (e.g. etcd3 Python client, Rust clients) generate their own bindings from the .proto files in this module.

Directory layout

api/
├── etcdserverpb/     # main RPC definitions (KV, Watch, Lease, Cluster, Maintenance, Auth)
│   ├── rpc.proto
│   ├── rpc.pb.go            (generated)
│   ├── rpc_grpc.pb.go       (generated)
│   ├── etcdserver.proto     # legacy v2 request type
│   ├── raft_internal.proto  # internal Raft proposal envelope
│   └── gw/                  # grpc-gateway REST shim (rpc.pb.gw.go)
├── authpb/           # User, Role, Permission protos
├── membershippb/     # ClusterVersionSetRequest, MemberAttributes, ...
├── mvccpb/           # KeyValue, Event protos
├── v3rpc/
│   └── rpctypes/     # Stable error-code definitions and translations
├── version/          # Compile-time version info (set via -ldflags)
└── versionpb/        # Cluster-version protos used by v3discovery

Key abstractions

Symbol	File	Description
etcdserverpb.KVServer (and KVClient)	api/etcdserverpb/rpc_grpc.pb.go	gRPC service handle for KV
etcdserverpb.WatchServer	same	gRPC service handle for streaming Watch
etcdserverpb.RangeRequest / PutRequest / TxnRequest	api/etcdserverpb/rpc.pb.go	Request types you'll see everywhere in the server
mvccpb.KeyValue	api/mvccpb/kv.pb.go	The unit returned by Range and Watch events
mvccpb.Event	same	PUT or DELETE event with previous KV
authpb.User / Role / Permission	api/authpb/auth.pb.go	RBAC objects
membershippb.ClusterVersionSetRequest	api/membershippb/membership.pb.go	Conf-change envelope for cluster version
version.Cluster / version.Server	api/version/version.go	Build-time version constants
rpctypes.ErrGRPC*	api/v3/v3rpc/rpctypes/error.go	Stable error codes, e.g. ErrGRPCKeyNotFound, ErrGRPCEmptyKey

How it is generated

scripts/genproto.sh regenerates everything in this module from the .proto sources, using the pinned protoc 3.20.3. scripts/verify_genproto.sh runs in CI to ensure the committed files match the source. Never hand-edit *.pb.go.

REST gateway

api/etcdserverpb/gw/rpc.pb.gw.go is the auto-generated grpc-gateway wrapper. Methods that include a (google.api.http) annotation in rpc.proto get a JSON/REST endpoint (e.g. POST /v3/kv/range). Methods without the annotation — most notably RangeStream — are gRPC-only.

Why it's a separate module

External Go consumers can vendor go.etcd.io/etcd/api/v3 without pulling in the server-side dependency cone. This used to be impossible; the workspace migration that completed in 3.6 (see lore.md) was largely motivated by users who couldn't update an etcd client without bumping every other transitive dep.

Entry points for modification

• New gRPC method or field → edit the relevant .proto, run scripts/genproto.sh, then implement on the server side under server/etcdserver/api/v3rpc/.
• New error code → api/v3/v3rpc/rpctypes/error.go, mirroring the existing ErrGRPCxxx / ErrXxx pair pattern.
• Bumping the cluster version → api/version/version.go plus server/etcdserver/version/.