Skip to content
Back to skills

Http

ASecurity

Hitting Connect RPC handlers with plain HTTP+JSON — URL shape, Content-Type rules, streaming caveats, and the `forge api curl` helper for building copy-pasteable curl invocations.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentgobashapibackend

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill http --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Http?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Http
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-http/badge)](https://www.skillsdirectory.com/skills/reliant-labs-http)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: api-http
description: Hitting Connect RPC handlers with plain HTTP+JSON — URL shape, Content-Type rules, streaming caveats, and the `forge api curl` helper for building copy-pasteable curl invocations.
---

# Plain HTTP + JSON against Connect RPCs

Forge generates Connect RPC handlers. Connect already speaks **plain HTTP/1.1 POST with `Content-Type: application/json`** for unary RPCs — no gRPC tooling required. `grpcurl`, `protoc`, and the connect-go client are convenient but optional. Any HTTP client (curl, HTTPie, Postman, the `fetch` in your browser console, a Lambda function) can call a forge backend directly.

## URL shape

```
POST /<fully.qualified.proto.package>.<ServiceName>/<MethodName>
```

The fully qualified service name is `<package>.<Service>`. Take it from your `.proto` file: the `package` directive plus the `service` block name.

```proto
// proto/services/users/v1/users.proto
package services.users.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}
```

→ POST endpoint: `/services.users.v1.UserService/GetUser`

The leading slash is part of the URL. There is **no** `/api/`, `/v1/`, or any other prefix — Connect serves directly off the package + service path.

## Required headers

| RPC kind | Content-Type | Notes |
|----------|--------------|-------|
| Unary | `application/json` | The default — what `curl -X POST -H 'Content-Type: application/json'` gives you. |
| Server-streaming | `application/connect+json` | Frames are length-prefixed; curl will only show the first frame. |
| Client-streaming | `application/connect+json` | Same framing; rarely useful from curl. |
| Bidi-streaming | `application/connect+json` | Same framing. |

If you forget `Content-Type` entirely, the server responds with `415 Unsupported Media Type`. The body must be the JSON representation of the request message — not the response, not a query string.

## Request body shape

ProtoJSON: a JSON object with one key per proto field. Connect accepts both `snake_case` and `camelCase`; forge's proto definitions use `snake_case`, which is what the `forge api curl` skeleton emits.

```json
{
  "id": "abc123",
  "include_deleted": false
}
```

Empty input messages (`google.protobuf.Empty`) require an empty body: `{}`. Methods that take only optional fields can also send `{}` — fields default to their proto zero values.

## Curl example (unary)

```bash
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"id":"abc123"}' \
  http://localhost:8080/services.users.v1.UserService/GetUser
```

Response (success):

```json
{"user":{"id":"abc123","name":"Alice"}}
```

Response (error — Connect maps RPC error codes to HTTP status):

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{"code":"not_found","message":"user not found"}
```

Common error codes: `invalid_argument` (400), `unauthenticated` (401), `permission_denied` (403), `not_found` (404), `already_exists` (409), `internal` (500). See `<https://connectrpc.com/docs/protocol/#error-codes>` for the full table.

## Auth headers

Every rpc requires a credential unless it declares `auth_required: false`. Pass a bearer token, or an API key once the project enables keys (`auth/api-keys`):

```bash
# JWT
curl -X POST -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{}' \
  http://localhost:8080/services.users.v1.UserService/ListUsers

# API key
curl -X POST -H 'Content-Type: application/json' \
  -H 'X-API-Key: <key>' \
  -d '{}' \
  http://localhost:8080/services.users.v1.UserService/ListUsers
```

Methods that declare `(forge.v1.method).auth_required = false` skip the auth interceptor and accept anonymous calls. The `auth` skill has the full table.

## Streaming RPCs

Server- and client-streaming RPCs use Content-Type `application/connect+json`. Each frame is wire-prefixed with a 5-byte header (1-byte flags + 4-byte length). curl can send the first frame but does not parse subsequent ones — for streaming work, reach for `grpcurl`, the connect-go client, or a small Go script using `connect.NewClient`.

Quick check that a streaming endpoint is reachable and accepts your input:

```bash
curl -X POST \
  -H 'Content-Type: application/connect+json' \
  -d '{"query":"all"}' \
  http://localhost:8080/events.v1.EventService/Subscribe
```

You will see the first response frame plus a connection that stays open until the server closes it.

## The `forge api curl` helper

`forge api curl <service.method>` builds a copy-pasteable curl command for you — no remembering the URL shape, no looking up the request message fields:

```bash
forge api curl services.users.v1.UserService.GetUser
# →
# curl -X POST \
#   -H 'Content-Type: application/json' \
#   -d '{"id":""}' \
#   http://localhost:8080/services.users.v1.UserService/GetUser
```

The body is a zero-value skeleton populated from the proto definition's fields, in declaration order. Edit it before sending.

Flags:

| Flag | Effect |
|------|--------|
| `--port <n>` | Port to hit; defaults to 8080 (e.g. when running behind a port-forward). |
| `--body '{...}'` | Skip the skeleton; use this JSON body verbatim. |
| `--host <name>` | Override the host (default: `localhost`). |

Short form works when the service name is unique across all proto packages:

```bash
forge api curl UserService.GetUser
```

The helper reads `gen/forge_descriptor/` for the proto data — run `forge generate` first if you've just added an RPC.

## Common pitfalls

1. **Missing the leading slash** — the URL path *is* `/<pkg>.<Service>/<Method>`, not `<pkg>.<Service>/<Method>`. Without the slash you'll get a 404.
2. **Wrong Content-Type for streaming** — `application/json` only works for unary RPCs. Streaming returns `415` if you forget `+json`.
3. **Forgetting the body for empty-input methods** — Connect requires `{}` even for `google.protobuf.Empty`. An empty `-d ''` produces a parse error.
4. **Confusing the URL with the proto file path** — the URL is built from the `package` directive (`/services.users.v1.UserService/GetUser`), not the file path: the `proto/` root and the file name (`users.proto`) never appear in it.
5. **Hand-rolling the URL when `forge api curl` exists** — let the helper read the descriptor; it will catch service/method renames at the point of use.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.