Engineering Note by Yasin Engin

Designing gRPC APIs for Network Control Planes

Design principles for low-friction gRPC APIs used by controllers and network services.

Keep the API boring and explicit

Network services benefit from deterministic interfaces. Favor explicit request objects and stable enums over ad-hoc string fields.

API conventions

• Keep method names verb based (ApplyConfig, GetStatus, StreamTelemetry).
• Version protobuf packages from day one.
• Use clear error details with machine-readable codes.
• Prefer server streaming for telemetry snapshots.

Avoid this anti-pattern

Do not overload one generic RPC method for everything. It increases coupling and makes observability harder.

Deployment note

Use mTLS between internal services and pin certificate rotation dates in your runbook.