Capi for Rust
Write the endpoints. Ship everywhere.
Capi is a modular, type-safe framework for building API clients in Rust —
REST first, with WebSocket, gRPC, GraphQL, HTML forms, and multipart/mixed
batching on the same foundation. You define each endpoint once as a plain Rust
type, and the framework delivers it across every HTTP backend, wire format, and
execution model your users might need — synchronous or asynchronous, native or
browser, JSON or XML or protobuf or a raw binary protocol.
The framework is deliberately unopinionated where it matters and deeply opinionated where it helps. Transport, wire format, and runtime belong to the application author and are exposed through swappable traits. Endpoint definition, the pipeline, authentication, rate limiting, and response decoding are built in, batteries included, so a client author can focus on the one thing only they can describe: the API itself.
The crates are at 0.5 and unpublished, on the way to a 1.0 whose public API is stable. Expect breaking changes before then.
Who this book is for
Two audiences, tagged throughout:
- Consumers use a client someone else shipped. You pick an HTTP client and a
codec (or take the defaults), authenticate, and call
query(). Your path: The Decoupling Thesis → Quick Start → Consuming and Patching a Client, dipping into Errors, Auth, and Clients, Lanes, and the Request Budget as needed. - Authors build or patch a client. Your path is the whole book, roughly in order: it mirrors how you actually build one — scaffold, config, auth, errors, decoders, types, endpoints, then the advanced and cross-cutting concerns.
If you read nothing else first, read The Five Ideas and the Request Lifecycle. Everything else is an elaboration of it.
A recurring cast
A handful of production client crates appear as worked examples throughout, so the code you read has continuity rather than a fresh toy per chapter:
| Crate | What it proves |
|---|---|
grok_capi_rs | JSON, bearer + named-tier auth, SSE streaming, deferred polling, WebSocket, gRPC client streaming, multipart, pagination, resumable downloads |
google_places_capi_rs | API-key-in-header, OAuth2/JWT flows, typed header params (field masks) |
aws_s3_capi_rs | AWS SigV4 signing, presigned URLs, XML codec, raw and aws-chunked bodies, per-operation error enums |
icecast_connect_capi_rs | resumable/auto-reconnecting streams, a custom binary protocol, a codec-free client |
ringcentral_capi_rs | generic OAuth2 with a JWT-bearer grant as the default scheme |
paychex_capi_rs | a derived auth scheme that renews its own credential |
azure_tables_capi_rs | Azure SharedKey signing, OData batches and changesets |
graphqlzero_capi_rs | the readable GraphQL reference |
Design decisions are pointed out throughout — why things are the way they are, and where the escape hatches lie — so you can tell a hard requirement from a convenience with an opt-out.