Eve library

Demeter API Reference

Guide

Revision 1

On this page

The Demeter REST API is self-documenting via an OpenAPI 3.1 specification generated from the route schemas at runtime. This page is the entry point; the authoritative, always-current reference is the generated spec itself.

Where the docs live#

Resource URL Notes
Interactive Swagger UI GET /docs Try-it-out console, filter, deep links
OpenAPI 3.1 JSON GET /docs/json Machine-readable; feed to client/codegen tooling

Both are wired in apps/demeter/api/src/plugins/swagger.ts (@fastify/swagger

  • @fastify/swagger-ui), registered in buildServer() before the routes so the spec captures every endpoint's schema.

Versioning#

All resource endpoints live under the /v1 prefix. Health probes (/health, /health/ready) are unversioned. The spec's info.version tracks the API package version.

Authentication#

Most endpoints require a Bearer JWT (declared as the BearerAuth security scheme in the spec):

text
Authorization: Bearer <access-token>

Obtain a token via POST /v1/auth/login (or the OAuth / magic-link flows under /v1/auth/*). IoT clients may instead present an API key — see the /v1/auth API-key endpoints. Tokens rotate via refresh tokens with family-based reuse detection.

Documented domains#

The spec is tagged by feature area; each tag groups its endpoints in the UI:

Tag Prefix Covers
Health /health Liveness / readiness probes
Gardens /v1/gardens Gardens, beds, membership/sharing
Plants /v1/plants Plant database, companion planting
Plantings /v1/plantings Seed-to-harvest lifecycle tracking
Tasks /v1/tasks Maintenance task scheduling & completion
Harvests /v1/harvests Harvest recording, yield analytics
Sensors /v1/sensors IoT sensors + time-series readings
Weather /v1/weather Weather data, forecasts, frost alerts
Observations /v1/observations Field notes & photo documentation
(AI) /v1/ai Algorithmic recommendations & inference
(Community) /v1/community Posts, comments, challenges, leaderboard

Exporting the spec#

To produce a static openapi.json for SDK generation or publishing, boot the server and fetch the JSON:

bash
pnpm --filter @demeter/api dev &        # or: build && start
curl -s http://localhost:3000/docs/json > openapi.json

Guarantees (enforced by tests)#

test/integration/openapi.integration.spec.ts fails the build unless the generated spec stays complete: OpenAPI 3.1, the BearerAuth scheme, all domain tags, ≥ 20 documented paths, and — critically — every operation carries a summary, a tag, and at least one response. A new endpoint that ships without schema annotations breaks this test, so the reference can never silently drift out of date.