How to Define Nested API Routes in 9router: A Complete Guide to App Router Patterns

9router leverages Next.js 13's App Router to define nested API routes through folder hierarchy, where each folder under src/app/api represents a URL segment and route.js files export HTTP method handlers.

9router is a Next.js-based framework that simplifies backend API development by adopting the App Router convention. Understanding how to define nested API routes in 9router allows you to build hierarchical REST endpoints without manual route configuration. This guide walks through the folder-based routing system using real examples from the decolua/9router repository.

How 9router's Folder-Based Routing Works

9router uses Next.js 13's App Router architecture to map directory structures directly to URL paths. Every folder created under src/app/api automatically becomes a route segment, with route.js (or route.ts) files serving as the entry point for HTTP requests.

The framework follows a zero-config approach: nested folders create nested URL paths, and dynamic segments use bracket notation like [id]. This convention eliminates the need for external routing libraries or manual route registration.

Creating Simple Routes in 9router

Single-Level Endpoints

A basic API route requires a single folder with a route.js file. For example, the version endpoint in src/app/api/version/route.js handles requests to /api/version.

// src/app/api/version/route.js
export async function GET() {
  const data = { version: "1.0.0" };
  return new Response(JSON.stringify(data), { status: 200 });
}

Defining Nested API Routes

Multi-Level Folder Structure

To create nested routes, add subfolders under src/app/api. Each subfolder appends to the URL path. The file src/app/api/version/update/route.js automatically serves /api/version/update.

// src/app/api/version/update/route.js
export async function GET() {
  const data = { version: "2.3.1", notes: "Minor bug fixes" };
  return new Response(JSON.stringify(data), { status: 200 });
}

Deep Nesting Example

For complex hierarchies like /api/users/settings, create the corresponding folder chain:

src/app/api/
└── users/
    └── settings/
        └── route.js

Then implement the handler with multiple HTTP methods:

// src/app/api/users/settings/route.js
export async function GET(request) {
  return new Response(JSON.stringify({ theme: "dark" }), { status: 200 });
}

export async function POST(request) {
  const body = await request.json();
  return new Response(JSON.stringify({ ok: true }), { status: 200 });
}

Working with Dynamic Route Segments

Dynamic parameters use bracket syntax in folder names. The route src/app/api/providers/[id]/models/route.js captures the id value from URLs like /api/providers/123/models.

Access parameters through the params object passed to handler functions:

// src/app/api/providers/[id]/models/route.js
export async function POST(request, { params }) {
  const { id } = params;
  const { model } = await request.json();
  await saveModelForProvider(id, model);
  return new Response(JSON.stringify({ saved: true }), { status: 201 });
}

Handling HTTP Methods and Request Data

Each route.js file exports async functions named after HTTP verbs. Supported methods include GET, POST, PUT, DELETE, and PATCH.

The request object provides standard Web API methods for accessing data:

export async function POST(request) {
  const headers = request.headers;
  const body = await request.json();
  
  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

Summary

• Folder hierarchy defines URL structure: Create folders under src/app/api to match your desired endpoint paths.
• Route files handle HTTP verbs: Export GET, POST, or other methods from route.js files to respond to specific request types.
• Dynamic segments use brackets: Name folders [param] to capture variable values from URLs, accessible via the params argument.
• Zero configuration required: Next.js automatically registers routes based on the file system, eliminating manual routing setup.

Frequently Asked Questions

What file naming convention does 9router use for API routes?

9router requires files to be named exactly route.js or route.ts within the API folder structure. This specific naming convention tells Next.js to treat the file as a Route Handler rather than a page component.

How do I access URL parameters in nested routes?

For dynamic segments like [id], destructure the params object from the second argument of your handler function. For example, export async function GET(request, { params }) allows you to access params.id to retrieve the value from the URL path.

Can I use TypeScript for 9router API routes?

Yes, rename your files from route.js to route.ts and use TypeScript syntax. The framework supports TypeScript natively through Next.js, allowing you to type the request object and response returns for better developer experience.

How does 9router handle different HTTP methods in the same route?

You can export multiple method handlers from the same route.js file. Define separate GET, POST, PUT, and DELETE functions in the same file, and Next.js will automatically route incoming requests to the matching handler based on the HTTP verb used.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}