agent-rules-kit/templates/stacks/nextjs/v13/api-routes.md

Bootstrap of **Cursor** rules (`.mdc`) and mirror documentation (`.md`) for AI agent-guided projects.

# Next.js 13 API Route Best Practices

## Overview

API routes in Next.js 13 provide a streamlined way to build backend functionality for your applications. With the introduction of the App Router, Next.js now emphasizes Route Handlers, which are functions exported from `route.js` files within the `app` directory. These handlers allow you to create API endpoints by leveraging native `Request` and `Response` objects, offering more flexibility and aligning closer to web standards.

## Key Guidelines

-   **Utilize Route Handlers in the `app` directory for new API endpoints.** This is the recommended approach for building APIs in Next.js 13+.
-   **Organize API routes logically within the `app` directory.** For example, an endpoint to fetch a user by ID could be located at `app/api/users/[id]/route.js`.
-   **Leverage native `Request` and `Response` objects** for handling HTTP requests and responses. This provides a powerful and standardized way to interact with incoming requests and formulate outgoing responses.
-   **Implement proper error handling and consistent JSON responses.** Ensure your API routes gracefully handle errors and return meaningful JSON responses with appropriate status codes.
-   **Secure API routes using appropriate authentication and authorization mechanisms.** Tools like NextAuth.js or custom middleware can be integrated to protect your endpoints.
-   **Consider using Edge Functions for API routes that require low latency or are geographically distributed.** Next.js supports deploying Route Handlers as Edge Functions, which can improve performance for users across different regions.

## Simple GET Example

This example demonstrates a basic GET request handler that returns a JSON message.

```javascript
// File: app/api/hello/route.js
export async function GET(request) {
  return new Response(JSON.stringify({ message: 'Hello, world!' }), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
    },
  });
}
```

## POST Example with Data Validation

This example shows how to handle POST requests, including basic data validation and error handling.

```javascript
// File: app/api/submit/route.js
export async function POST(request) {
  try {
    const body = await request.json();

    // Basic validation
    if (!body.name || !body.email) {
      return new Response(JSON.stringify({ error: 'Name and email are required' }), {
        status: 400,
        headers: { 'Content-Type': 'application/json' },
      });
    }

    // Process data (e.g., save to database)
    console.log('Received data:', body);

    return new Response(JSON.stringify({ message: 'Data received successfully', data: body }), {
      status: 201,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    console.error('API Error:', error);
    return new Response(JSON.stringify({ error: 'Invalid request body or server error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}
```

## Dynamic Route Example

This example illustrates how to create dynamic API routes where parts of the URL path are parameters.

```javascript
// File: app/api/items/[id]/route.js
export async function GET(request, { params }) {
  const itemId = params.id;

  // Fetch item from a data source based on itemId
  // For example: const item = await getItemById(itemId);

  if (!itemId) { // Replace with actual check, e.g., !item
    return new Response(JSON.stringify({ error: 'Item not found' }), {
      status: 404,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  return new Response(JSON.stringify({ id: itemId, name: `Item ${itemId}` }), { // Replace with actual item data
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
}
```