# Demeter API Reference

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):

```
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.
