> ## Documentation Index
> Fetch the complete documentation index at: https://rydantic.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# One model across HTTP, OpenAPI and gRPC

> Forward validated HTTP JSON through a Cap'n Proto gRPC service and publish the HTTP contract.

> [!WARNING]
>
> The `grpc` feature used here is source-only and is not included in the published `rydantic = "=0.8.0"` package. The `capnp`, `axum`, and `openapi` features are available in 0.8.0.

## Run the bridge

Install the official Cap’n Proto compiler, then run the combined example from a source checkout:

cargo run --locked -p rydantic --example protocol\_bridge --features "grpc axum openapi"

The example starts a local Tonic backend and an Axum HTTP gateway. It prints the HTTP address and serves:

* `POST /greet` — validates JSON into the shared `Hello` model, encodes it as Cap’n Proto, calls the unary gRPC method, then returns the validated `Greeting` as JSON.
* `GET /openapi.json` — returns an OpenAPI 3.1 document with input and output schemas generated from those same models.

The OpenAPI operation includes `x-rydantic-grpc-method` to record the corresponding Tonic method path. The example explicitly wires the HTTP route, Tonic service and OpenAPI operation.

The request path is:

HTTP JSON → Rydantic validation → Cap’n Proto encoding → Tonic unary gRPC
← JSON response     ← Rydantic validation ← Cap’n Proto decoding

Try it using the address printed by the example:

```sh theme={"system"}
curl -H 'content-type: application/json' \
  -d '{"name":" Alice ","context":{"language":"en"}}' \
  http://127.0.0.1:<printed-port>/greet

curl http://127.0.0.1:<printed-port>/openapi.json
```

Before contacting the backend, the gateway checks the encoded Cap’n Proto request size against its configured gRPC message limit. Oversized HTTP bodies or encoded requests return `413`; request validation or local encoding failures return `422`. Backend and response failures remain redacted `502` responses, including a backend's `InvalidArgument` status.

The example binds both listeners to loopback and runs until stopped. It has no authentication, TLS, rate limiting or deployment configuration.

## Wire contract

The gRPC hop uses the existing `CapnpModel` wire types and Tonic custom codec. Both peers must use the same service method path, Cap’n Proto root type, field ordinals and field types. This is unary Cap’n Proto serialization over gRPC; standard protobuf clients, `.proto` generation, reflection, streaming, and native Cap’n Proto RPC are not part of this adapter.

The OpenAPI document describes the HTTP gateway operation. Its vendor extension records the gRPC method mapping; it does not create routes or transcode requests by itself. Other-language gRPC peers need a matching Cap’n Proto codec and service implementation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.