Add an API Endpoint

Goal

Add a new endpoint to wordloop-core, following the spec-first workflow so that the server handler, the TypeScript client, and the reference docs all stay aligned.

Prerequisites

• Local stack running (./dev start all) — see Quickstart.
• Familiarity with API Design and Hexagonal Architecture principles.

Steps

1. Update the OpenAPI spec

The spec is the source of truth. Open specs/core-openapi.json and add your endpoint:

• Path, method, operationId.
• Request and response schemas with descriptions on every field.
• Example payloads.
• Error responses mapped to our standard error codes (Reference / Errors).

2. Regenerate handlers and clients

./dev generate core

This produces the server-side handler stub and the TypeScript client surface. See Code Generation for details on what runs under the hood.

3. Implement the handler

Fill in the generated handler stub. Handlers stay thin — extract inputs, call the application service, shape the response. Business rules belong in the domain; orchestration belongs in the application service.

4. Write a service test

In the handler's test file, spin up the Testcontainers Postgres, make the HTTP call, assert on behaviour and on the OTel trace shape. See Testing for the discipline.

5. Run the relevant checks

./dev lint core
./dev test core

Verification

• ./dev test core passes.
• The Core API Reference renders the new endpoint automatically.
• Hitting the endpoint from the local frontend produces the expected response.

Troubleshooting

• Generated code is out of date. Re-run ./dev generate core and commit the generated files.
• Testcontainers failing to start. Check ./dev status and that Docker is running.
• Frontend cannot reach the endpoint. The frontend uses the generated TypeScript client; re-running generation and restarting the Next.js dev server usually fixes it.

See API Design for the stance this workflow expresses.