Basic API

examples/basic-api in the Routa repository is the smallest complete project: a handful of routes, route-local schemas, and committed .routa/ metadata. It is the shape the scaffolder produces, with enough routes to show nesting and dynamic segments.

pnpm install
pnpm --filter basic-api dev

curl http://127.0.0.1:3000/users/usr_1

What Is Inside

Directorysrc/
- routa.ts
- Directoryroutes/
  - Directorystatus/
    route.ts
    schemas.ts
  - Directoryusers/
    route.ts
    schemas.ts
    Directory$userId/
    route.ts
    schemas.ts
    Directoryposts/
    route.ts
    schemas.ts
  - Directorydemo/
    route.ts

How It Works

src/routes/users/route.ts and src/routes/users/$userId/route.ts show the two halves of a collection resource: one file owns /users, another owns /users/:userId. Neither knows about the other, because the URL comes from the file’s location rather than from a registry.

Every route keeps its Zod schemas in a sibling schemas.ts. That is the default convention, and it is what makes a route directory a self-contained unit you can move.

src/routes/users/$userId/posts/route.ts demonstrates that nesting continues past a dynamic segment: the parent parameter is still available in input.params because it is part of the resolved path.

What to Study

File	Shows
`src/routa.ts`	The minimum configuration a project needs
`src/routes/status/route.ts`	The smallest possible contract
`src/routes/users/route.ts`	A collection with more than one method
`src/routes/users/$userId/route.ts`	A validated path parameter
`.routa/routes.gen.ts`	What Routa derived from all of the above

Limits

This example has no middleware, no authentication, and no persistence. Handlers return in-memory data so the HTTP boundary stays legible. For middleware chains, route groups, and OpenAPI workflows, read the Full API example.

Next Steps

Full APIMiddleware, groups, deprecation, and logging.

First routeBuild this shape yourself.

RoutingWhy these files map to those URLs.