# `reference/rest/` — HTTP test files for the `.wo` runtime

`.rest` (or `.http`) is the plain-text HTTP-request format supported by the two main editor HTTP clients:

- **VS Code** — install [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) (`humao.rest-client`) and click "Send Request" above any block.
- **JetBrains IDEs** (IntelliJ, WebStorm, RustRover, Goland) — built-in HTTP Client recognises `.rest` and `.http` natively.

Both clients understand:

- `### ...` block separators
- `@var = value` document-level variables referenced as `{{var}}`
- `# @name foo` on a request, whose response fields are later reachable as `{{foo.response.body.id}}` — useful for threading auto-generated ids from `create` responses into later `get`/`patch`/`delete` calls

## Files

| File | Against | What it exercises |
| --- | --- | --- |
| [`blog.rest`](./blog.rest) | `docs/examples/blog/` | Full CRUD on Article/Comment, read-only on Author/Tag (matches the sample's `expose` lists). End-to-end flow: create article → list → get by id → PATCH title → PATCH embedded doc → DELETE draft → verify final state. |
| [`ecommerce.rest`](./ecommerce.rest) | `docs/examples/ecommerce/` | What Stage 2 currently serves for the ecommerce sample: read-only Product/Order/Customer lists, 405s for non-exposed create endpoints, 501s for Stage 3 stubs. Documents the shape of Stage 3/4 endpoints (`fn checkout`, LIVE subscribe, `/me`) even though they're not wired yet. |

## Running

```bash
# one terminal — start the runtime
cargo run --bin wo -- run docs/examples/blog
#    [wo] listening on http://127.0.0.1:8080

# another terminal — or just open the .rest file in VS Code/JetBrains and click
```

Override the port via `WO_LISTEN`:

```bash
WO_LISTEN=127.0.0.1:9000 cargo run --bin wo -- run docs/examples/blog
```

…and update the `@host` line at the top of the `.rest` file to match.

## Without an editor (just `curl`)

Each `.rest` block maps directly to `curl`. Some examples:

```bash
# Runtime info
curl http://127.0.0.1:8080/

# List
curl http://127.0.0.1:8080/api/articles

# Create — server assigns `id` automatically
curl -X POST http://127.0.0.1:8080/api/articles \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "hello-writeonce",
    "title": "Hello, writeonce",
    "author": 1,
    "published": true,
    "meta": { "excerpt": "first post", "body_md": "# hi" }
  }'

# Get by id
curl http://127.0.0.1:8080/api/articles/1

# Partial update
curl -X PATCH http://127.0.0.1:8080/api/articles/1 \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated" }'

# Delete
curl -X DELETE http://127.0.0.1:8080/api/articles/1    # 204 on success

# Stage 3 stub
curl -i http://127.0.0.1:8080/api/articles/live        # 501 Not Implemented
```

For a scripted smoke run against the blog sample, the top-to-bottom `curl` sequence that exactly mirrors `blog.rest` is in [`docs/examples/blog/README.md`](../../docs/examples/blog/README.md).

## Expected-status cheat sheet

Every block in the `.rest` files ends its description with the expected HTTP status. Quick legend:

| Status | Meaning in this prototype |
| --- | --- |
| `200` | OK — list / get / update succeeded |
| `201` | Created — new row, `id` in the response body |
| `204` | No Content — delete succeeded |
| `400` | Bad JSON body |
| `404` | No such row, OR no method at all is attached to the path (e.g. `/api/customers` when the `service rest` block doesn't `expose` any collection-root op) |
| `405` | Method not allowed — the path is registered for a *different* method (e.g. POST against `/api/products` when only `list` is exposed, so GET is attached but POST isn't) |
| `501` | Not Implemented — Stage 3+ feature (LIVE subscriptions, `/me`, transactional fns) |

A `405` is a *feature* of the sample — it confirms the `expose` list in the `.wo` file is being honoured. A `501` is a Stage marker — the runtime acknowledges the shape but hasn't wired the handler yet.