Routing

Define how procedures map to HTTP methods, paths, and response statuses.

WARNING

This feature applies only when using OpenAPIHandler.

Basic Routing

By default, oRPC uses the POST method, constructs paths from router keys with /, and returns a 200 status on success. Override these defaults with .route:

os.route({ method: 'GET', path: '/example', successStatus: 200 })
os.route({ method: 'POST', path: '/example', successStatus: 201 })

Path Parameters

By default, path parameters merge with query/body into a single input object. You can modify this behavior as described in the Input/Output structure docs.

os.route({ path: '/example/{id}' })
  .input(z.object({ id: z.string() }))

os.route({ path: '/example/{+path}' }) // Matches slashes (/)
  .input(z.object({ path: z.string() }))

Route Prefixes

Use .prefix to prepend a common path to all procedures in a router that have an explicitly defined path:

const router = os.prefix('/planets').router({
  list: listPlanet,
  find: findPlanet,
  create: createPlanet,
})

WARNING

The prefix only applies to procedures that specify a path.

Lazy Router

When combining a Lazy Router with OpenAPIHandler, a prefix is required for lazy loading. Without it, the router behaves like a regular router.

INFO

If you follow the contract-first approach, you can ignore this requirement—oRPC knows the full contract and loads the router lazily properly.

const router = {
  planet: os.prefix('/planets').lazy(() => import('./planet'))
}

Default Configuration

Customize the default oRPC routing settings using .$route:

const base = os.$route({ method: 'GET' })