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
- The
shopproject from Add a database table with a CRUD API and pages. - Forge v1.6 or later. Inside Reliant, run it as
reliant forge. - Docker for the local stack. No account.
1
Turn REST and OpenAPI on
Add an The two are independent; with both on, the spec documents the REST URLs.
api block to forge.yaml:forge.yaml
2
Wire the transcoder into the server
A project created with Add the googleapis module, which holds Commit the
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
google/api/annotations.proto, to buf.yaml and lock it:buf.yaml
terminal
buf.lock it writes.3
Map RPCs to URLs
Give each RPC you want over REST a An unannotated RPC keeps only its Connect URL. Keep REST paths under a prefix such as
google.api.http option. {id} fills a request field; body: "*" maps the JSON body onto the request:proto/services/catalog/v1/catalog.proto
/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 Query parameters fill the other request fields, so
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
?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
imported file does not exist (google/api/annotations.proto)
imported file does not exist (google/api/annotations.proto)
buf.yaml has no googleapis dependency, or buf.lock is missing. Add the deps entry from the second step and run buf dep update.module declares its path as: connectrpc.com/protoc-gen-connect-openapi
module declares its path as: connectrpc.com/protoc-gen-connect-openapi
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.REST request returns 404 page not found
REST request returns 404 page not found
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