Getting started

Prerequisites

Follow Local development: make dev-up and make migrate.

Start the API

make dev-template

• API: localhost:8081
• Swagger UI: localhost:8081/api-docs
• Database: postgres://postgres:postgres@localhost:5433/template

Authorization is not wired in the template service yet — endpoints are open aside from Idempotency-Key on writes.

Create a domain1 record

curl -s -X POST localhost:8081/v1/domain1 \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"data":{"value":"hello"}}' | jq

Get by id

curl -s localhost:8081/v1/domain1/{id} | jq

Domain2 uses the same shape at /v1/domain2/{id}.

List

curl -s 'localhost:8081/v1/domain1?pagination[page]=1&pagination[pageSize]=25' | jq

The payload is { data: [...], meta: { pagination } }. Create and get use { data: { …record } }. See ADR 0014. Domain2 uses the same shape at /v1/domain2.

Watch the fanout

In another terminal, after make dev-up:

make dev-domain1listener

Create a domain1 record and the listener logs an event received line from template-domain1-queue-listener, carrying the same requestId the API returned in X-Request-Id. make dev-domain2listener does the same for domain2.

Follow one request

curl -si -X POST localhost:8081/v1/domain1 \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"data":{"value":"hello"}}' | grep -i x-request-id

That id appears on the API's request line, on the publisher's line, and on the listener's. Supply your own with -H "X-Request-Id: <id>" and it is echoed rather than replaced.

Logs go to stderr — stdout belongs to -openapi. LOG_LEVEL=debug adds the full broker message; LOG_FORMAT=json shows locally what a deployed environment emits. See ADR 0017.

Generate OpenAPI

go run ./services/template/cmd/api -openapi > /tmp/template-openapi.yaml

The checked-in spec is services/template/openapi.yaml↗.