Skip to main content
You will make GET /v1/products, GET /v1/products/{id} and POST /v1/products answer from the catalog service’s existing handlers, and generate an OpenAPI 3 spec for them, so clients that do not speak Connect get a plain REST API. There is no second API. With api.rest on, a transcoder in front of the Connect handlers reads the proto’s google.api.http annotations and relays each matching request to the same handler, through the same interceptors, auth included. The spec comes from the same proto during generate.

Before you begin

1

Turn REST and OpenAPI on

Add an api block to forge.yaml:
forge.yaml
The two are independent; with both on, the spec documents the REST URLs.
2

Wire the transcoder into the server

A project created with api.rest: true comes wired. In an existing one these files are yours, so you make the change. Turn on the REST handler:
internal/app/providers.go
Add the googleapis module, which holds google/api/annotations.proto, to buf.yaml and lock it:
buf.yaml
terminal
Commit the buf.lock it writes.
3

Map RPCs to URLs

Give each RPC you want over REST a google.api.http option. {id} fills a request field; body: "*" maps the JSON body onto the request:
proto/services/catalog/v1/catalog.proto
An unannotated RPC keeps only its Connect URL. Keep REST paths under a prefix such as /v1/ so no other route shadows them.
4

Install the OpenAPI plugin and generate

The spec comes from protoc-gen-connect-openapi, a Go plugin you install once per machine:
terminal
generate writes one spec per service proto under openapi/, named after the proto file. Commit it so a drift check catches a stale spec, or publish it from a build job. Never edit it by hand.
5

Verify the REST routes

Start the API with reliant forge env up dev, sign in as the development user from idp-steps.yaml, and call the new URLs with the session cookie:
terminal
Query parameters fill the other request fields, so ?search= and ?page_size= work. Errors map to HTTP statuses: an unknown ID is 404 with {"code":5,"message":"product not found"}, no session is 401, an unmapped method is 405. The Connect URLs still answer. Stop the stack with reliant forge env down dev.
6

Check the spec

Open the spec under openapi/. Annotated RPCs appear under their REST paths (/v1/products with get and post, /v1/products/{id} with get), the rest under their Connect paths. Import it into Postman, an API portal or openapi-generator.

What this does not do

  • No REST client code. For a typed client, feed the spec to a client generator.
  • No new access rules. A REST call runs the same interceptors and handler as the Connect call, so nothing opens that was not already open.
  • Most streams stay Connect-only. A streaming RPC maps to REST only when its streamed message is a google.api.HttpBody. Annotate any other and the REST routes fail at startup, leaving Connect only.

Troubleshooting

buf.yaml has no googleapis dependency, or buf.lock is missing. Add the deps entry from the second step and run buf dep update.
The plugin moved to connectrpc.com/protoc-gen-connect-openapi. Install it with go install connectrpc.com/protoc-gen-connect-openapi@latest, and make sure $(go env GOPATH)/bin is on your PATH.
No annotation matches, or the transcoder is off. Check REST: true, rerun generate, and look for init vanguard REST handler in .forge/logs/dev/api.log.

Next steps

Add a custom RPC

Write an RPC of your own, then give it a REST URL

Find endpoints missing auth checks

Audit what each RPC, and so each REST route, lets a caller do

How forge generate works

Where the proto projections, the spec among them, come from

Middleware and the request path

The interceptors a REST call passes through