gRPC-gateway REST

etcd exposes a JSON/HTTP gateway in front of the gRPC API, generated by grpc-gateway from the same .proto files.

How it's generated

In api/etcdserverpb/rpc.proto, every method that should have a REST mapping has a (google.api.http) annotation:

rpc Put(PutRequest) returns (PutResponse) {
    option (google.api.http) = {
        post: "/v3/kv/put"
        body: "*"
    };
}

scripts/genproto.sh drives protoc with protoc-gen-grpc-gateway, producing api/etcdserverpb/gw/rpc.pb.gw.go. The server then mounts the gateway alongside the gRPC server using grpc.HTTPHandler in server/embed/serve.go — same port, multiplexed by content-type and Content-Type: application/grpc-web detection.

URL shape

Endpoint	gRPC method
POST /v3/kv/range	KV.Range
POST /v3/kv/put	KV.Put
POST /v3/kv/deleterange	KV.DeleteRange
POST /v3/kv/txn	KV.Txn
POST /v3/kv/compaction	KV.Compact
POST /v3/watch	Watch.Watch (server-streamed JSON)
POST /v3/lease/grant, /v3/lease/revoke, /v3/lease/keepalive, /v3/lease/timetolive, /v3/lease/leases	Lease.*
POST /v3/cluster/member/add etc.	Cluster.*
POST /v3/auth/enable, /v3/auth/authenticate, /v3/auth/user/add, /v3/auth/role/grant, ...	Auth.*
POST /v3/maintenance/alarm, /v3/maintenance/status, /v3/maintenance/defragment, /v3/maintenance/hash, /v3/maintenance/snapshot, ...	Maintenance.*

Notable absence: KV.RangeStream does not have an HTTP mapping — chunked streaming results don't fit JSON/REST cleanly.

Body conventions

Bytes fields (key, value, range_end) are base64-encoded in JSON. The official OpenAPI/Swagger spec is published as part of the etcd docs (api/etcdserverpb/rpc.swagger.json is generated by scripts/genproto.sh when the swagger plugin is wired in).

When to use REST vs gRPC

• REST: ad-hoc curl, environments where adding a gRPC client is awkward.
• gRPC: production. Watch, lease keep-alive, and RangeStream only make sense in gRPC.

Cross-references

• api/grpc-services — full service inventory.
• reference/dependencies — protoc-gen-grpc-gateway is pinned in tools/mod/.