hydro turns resource definitions into REST endpoints, validation, relationships, OpenAPI output and Scalar docs — zero boilerplate.
Resource definition
Drop a file into server/resources, export defineResource(), and Hydro wires the routes, validation and documentation at runtime.
Zod validates request bodies and feeds the generated OpenAPI document.
Implement list/get against memory, SQL, KV, an external API, or your own repository layer.
Create, update and delete receive already-parsed input plus params, auth and request metadata.
Filters, relationships, auth rules and custom operations layer onto the same resource definition.
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).max(200), authorId: z.string().optional(), available: z.boolean().default(true), }), filters: ['title', 'authorId'], provider: { async list(ctx) { const { offset, itemsPerPage } = ctx.query.pagination return { items: books.slice(offset, offset + itemsPerPage), total: books.length, } }, async get(ctx) { return books.find(book => book.id === ctx.params.id) ?? null }, }, processor: { async create(ctx) { const book = { ...ctx.input, id: crypto.randomUUID() } books.push(book) return book }, async update(ctx) { return updateBook(ctx.params.id, ctx.input) }, async delete(ctx) { await deleteBook(ctx.params.id) }, },})
Explore the API
Classic CRUD, belongs-to references, filters, sparse fields and an item-level checkout action.
/api/books?fields=id,title,available&page=1&itemsPerPage=3↗Sparse fields with pagination/api/books?authorId=a3&available=false↗Combine relationship and boolean filters/api/books/1↗Fetch one book/api/books/1/checkoutRicher resource with filters, sorting, pagination limits, nested writes, custom actions and derived fields.
/api/authors?fields=id,name,country,bookCount↗Derived fields with sparse output/api/authors?country=US&featured=true&order[name]=asc&page=1&itemsPerPage=2↗Filtered, sorted and paginated/api/authors/a3↗Fetch one author/api/authors/spotlightCapability tour
Hydro parses the query string into ctx.query so providers can apply filters, sort rules, pagination and sparse fields in one place.
GET /api/authors?country=US&featured=true&order[name]=asc&page=1&itemsPerPage=2&fields=id,name,country,bookCount
Create a book by sending an author reference. Hydro resolves the relationship and writes the foreign key before your processor runs.
POST /api/booksContent-Type: application/json{ "title": "The Fifth Season", "author": "/authors/a5"}
Create a parent and child records together. The Author resource accepts nested books and Hydro attaches the generated author id.
POST /api/authorsContent-Type: application/json{ "name": "Martha Wells", "country": "US", "bio": "Science fiction and fantasy author.", "books": [ { "title": "All Systems Red" } ]}
Use named actions for behavior that is not plain CRUD. They still live under the resource, validate input and output, and appear in the generated docs.
POST /api/books/1/checkoutContent-Type: application/json{ "userId": "demo-user" }200 OK{ "id": "1", "available": false}POST /api/authors/spotlightContent-Type: application/json{ "country": "US" }
Clients get a predictable error contract instead of parsing framework-specific messages. Every violation points to the failing field.
POST /api/authorsContent-Type: application/json{ "name": "", "country": "USA" }422 Unprocessable EntityContent-Type: application/problem+json{ "type": "validation-error", "title": "Validation Error", "status": 422, "violations": [ { "path": "/name", "message": "Required" }, { "path": "/country", "message": "Expected 2 characters" } ]}
Nested writes
The author resource accepts nested book creation. Send this body to POST /api/authors to create a new author with one related book in a single request.
{ "name": "Martha Wells", "country": "US", "bio": "Science fiction and fantasy author.", "books": [ { "title": "All Systems Red" } ]}
Generated documentation