# hydro

Resource-oriented REST APIs for Nuxt and Nitro.

hydro creates CRUD routes, validation, query parsing, relationship writes, custom operations, RFC 7807 errors, and OpenAPI docs from resource definitions.

## Canonical AI context

Full context for AI coding tools:

https://hydro-playground.vercel.app/llms-full.txt

Repository:

https://github.com/muffe/hydro

Playground:

https://hydro-playground.vercel.app

Interactive API docs:

https://hydro-playground.vercel.app/api/_docs

OpenAPI spec:

https://hydro-playground.vercel.app/api/_openapi.json

## Key rules

- Configure Nuxt with `modules: ['@muffe/hydro']`.
- Put resources in `server/resources/` unless `hydro.resourcesDir` says otherwise.
- Import `defineResource` from `#hydro` in resource files.
- Use Zod schemas.
- Provider handles reads: `list(ctx)` and `get(ctx)`.
- Processor handles writes: `create(ctx)`, `update(ctx)`, `delete(ctx)`.
- Use `ctx.query` for filters, sort, pagination and sparse fields.
- Use `ctx.input` for validated request bodies.
- Use relationships for reference and nested writes.
- Use custom operations for actions that are not CRUD.
- Use OpenAPI docs at `/api/_docs` when enabled.

## Minimal resource

```ts
import { defineResource } from '#hydro'
import { z } from 'zod'

export default defineResource({
  name: 'Book',
  path: 'books',
  schema: z.object({
    id: z.string().optional(),
    title: z.string().min(1),
  }),
  provider: {
    async list(ctx) {
      return { items, total }
    },
    async get(ctx) {
      return item ?? null
    },
  },
  processor: {
    async create(ctx) {
      return created
    },
    async update(ctx) {
      return updated
    },
    async delete(ctx) {},
  },
})
```