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

# Expose REST endpoints and an OpenAPI spec from a Connect API

> Serve plain REST URLs such as GET /v1/products from your existing Connect RPC handlers, and generate an OpenAPI 3 spec from the same proto, with no second API.

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

* The `shop` project from [Add a database table with a CRUD API and pages](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md).
* 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 `api` block to `forge.yaml`:

```yaml forge.yaml theme={null}
api:
  rest: true      # serve REST URLs from google.api.http annotations
  openapi: true   # write an OpenAPI 3 spec per service during generate
```

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:

```go internal/app/providers.go theme={null}
		Front:  d.Probes.Front(),
		REST:   true,
	})
```

Add the googleapis module, which holds `google/api/annotations.proto`, to `buf.yaml` and lock it:

```yaml buf.yaml theme={null}
version: v2
modules:
  - path: proto
deps:
  - buf.build/googleapis/googleapis
```

```bash terminal theme={null}
buf dep update
```

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:

```protobuf proto/services/catalog/v1/catalog.proto theme={null}
import "google/api/annotations.proto";

service CatalogService {
  rpc CreateProduct(CreateProductRequest) returns (CreateProductResponse) {
    option (google.api.http) = { post: "/v1/products" body: "*" };
    option (forge.v1.method) = { auth_required: true  idempotency_key: true };
  }
  rpc GetProduct(GetProductRequest) returns (GetProductResponse) {
    option (google.api.http) = { get: "/v1/products/{id}" };
    option (forge.v1.method) = { auth_required: true };
  }
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse) {
    option (google.api.http) = { get: "/v1/products" };
    option (forge.v1.method) = { auth_required: true };
  }
  // ... the other RPCs stay Connect-only
}
```

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:

```bash terminal theme={null}
go install connectrpc.com/protoc-gen-connect-openapi@latest
reliant forge generate
```

`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:

```bash terminal theme={null}
curl -s -c cj -X POST localhost:8085/auth/login -H 'content-type: application/json' \
  -d '{"email":"admin@shop.localhost","password":"Password1!"}'
curl -s -b cj localhost:8085/v1/products/0134c82b-e994-5777-a85e-9f27cbf14f3f
curl -s -b cj -X POST localhost:8085/v1/products -H 'content-type: application/json' \
  -H 'Idempotency-Key: first-aeropress' -d '{"name":"Aeropress Go","priceCents":"3999","active":true}'
curl -s -b cj 'localhost:8085/v1/products?search=Aeropress&page_size=1'
```

```text theme={null}
{"product":{"name":"sample_name_5","priceCents":"5","active":true,"id":"0134c82b-e994-5777-a85e-9f27cbf14f3f",...}}
{"product":{"name":"Aeropress Go","priceCents":"3999","active":true,"id":"01M7WWC5SSFEYBP9KXD08FHP80",...}}
{"products":[{"name":"Aeropress Go","priceCents":"3999","active":true,...}],"nextPageToken":"","totalCount":1}
```

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

> [accordion] 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`.

> [accordion] 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`.

> [accordion] 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

> [card] [Add a custom RPC](https://docs.reliantlabs.io/guides/forge/add-custom-rpc.md)
>
> Write an RPC of your own, then give it a REST URL

> [card] [Find endpoints missing auth checks](https://docs.reliantlabs.io/guides/forge/find-endpoints-missing-auth-checks.md)
>
> Audit what each RPC, and so each REST route, lets a caller do

> [card] [How forge generate works](https://docs.reliantlabs.io/deep-dives/how-forge-generate-works.md)
>
> Where the proto projections, the spec among them, come from

> [card] [Middleware and the request path](https://docs.reliantlabs.io/forge/concepts/middleware-and-request-path.md)
>
> The interceptors a REST call passes through


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