Imported from NextSpark-js/nextspark (.claude/skills/nextjs-api-development/SKILL.md). Install upstream with npx skills add NextSpark-js/nextspark --skill nextjs-api-development. Copyright stays with the author.

Next.js API Development Skill

Patterns and tools for REST API development with Next.js 15 App Router.

Architecture Overview

app/api/v1/
├── [entity]/              # Dynamic CRUD (auto-generated from registry)
│   ├── route.ts          # GET (list) / POST (create)
│   └── [id]/route.ts     # GET (read) / PATCH (update) / DELETE
├── (contents)/           # Custom overrides (parentheses = not in URL)
│   └── tasks/            # Example: custom implementation
├── users/                # Core endpoints (not dynamic)
├── api-keys/             # API key management
├── auth/                 # Authentication endpoints
├── billing/              # Billing & subscriptions
├── teams/                # Team management
└── theme/                # Theme-specific endpoints

📍 Context-Aware Paths: Core API routes (app/api/v1/) are read-only in consumer projects. Create custom endpoints in app/api/ or override via (contents)/ pattern. See core-theme-responsibilities skill for complete rules.

When to Use This Skill

Creating new API endpoints
Implementing dual authentication
Adding custom business logic to entities
Debugging API issues
Testing API endpoints
Understanding API patterns

Core Patterns

Route Handler Pattern (MANDATORY)

All routes MUST use withApiLogging wrapper and addCorsHeaders:

import { NextRequest, NextResponse } from 'next/server'
import { queryWithRLS, mutateWithRLS } from '@/core/lib/db'
import {
  createApiResponse,
  createApiError,
  createPaginationMeta,
  parsePaginationParams,
  withApiLogging,
  handleCorsPreflightRequest,
  addCorsHeaders,
} from '@/core/lib/api/helpers'
import { authenticateRequest, createAuthFailureResponse } from '@/core/lib/api/auth/dual-auth'

// Handle CORS preflight
export async function OPTIONS() {
  return handleCorsPreflightRequest()
}

// GET /api/v1/[endpoint] - List resources
export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
  try {
    // 1. Authenticate (API Key OR Session). Declare the scope this route
    // needs — e.g. '<entity>:read' — an API key without it is rejected
    // here (fails closed, #93). See the `better-auth` skill for the full
    // scope-enforcement contract.
    const authResult = await authenticateRequest(req, { requiredScope: '<entity>:read' })

    if (!authResult.success) {
      return createAuthFailureResponse(authResult)
    }

    if (authResult.rateLimitResponse) {
      return authResult.rateLimitResponse as NextResponse
    }

    // 2. Parse pagination
    const { page, limit, offset } = parsePaginationParams(req)

    // 3. Fetch data with RLS
    const data = await queryWithRLS(
      `SELECT * FROM "table" WHERE 1=1 ORDER BY "createdAt" DESC LIMIT $1 OFFSET $2`,
      [limit, offset],
      authResult.user!.id
    )

    // 4. Create response with pagination
    const paginationMeta = createPaginationMeta(page, limit, total)
    const response = createApiResponse(data, paginationMeta)
    return addCorsHeaders(response)
  } catch (error) {
    console.error('[ENDPOINT] Error:', error)
    const response = createApiError('Failed to fetch data', 500)
    return addCorsHeaders(response)
  }
})

Response Helpers (MANDATORY)

import { createApiResponse, createApiError } from '@/core/lib/api/helpers'

// Success responses - always wrap with addCorsHeaders
const response = createApiResponse(data)
return addCorsHeaders(response)

const response = createApiResponse(data, { created: true }, 201)
return addCorsHeaders(response)

const response = createApiResponse(data, paginationMeta)
return addCorsHeaders(response)

// Error responses - always wrap with addCorsHeaders
const response = createApiError('Not found', 404)
return addCorsHeaders(response)

const response = createApiError('Validation error', 400, zodError.issues, 'VALIDATION_ERROR')
return addCorsHeaders(response)

Response Format

// Success
{
  "success": true,
  "data": { /* entity data */ },
  "info": {
    "timestamp": "2024-01-17T10:30:00Z",
    "pagination": { /* if applicable */ }
  }
}

// Error
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": { /* optional */ },
  "info": {
    "timestamp": "2024-01-17T10:30:00Z"
  }
}

Route Types

1. Dynamic Entity Routes

For standard CRUD operations. Automatically generated from EntityRegistry.

GET  /api/v1/products     → List products
POST /api/v1/products     → Create product
GET  /api/v1/products/123 → Read product
PATCH /api/v1/products/123 → Update product
DELETE /api/v1/products/123 → Delete product

When to use: Standard CRUD, basic validation, standard pagination.

2. Custom Override Routes

For special business logic. Use (contents)/ folder.

// app/api/v1/(contents)/tasks/route.ts
export const POST = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
  const authResult = await authenticateRequest(req, { requiredScope: 'tasks:write' })
  if (!authResult.success) {
    return createAuthFailureResponse(authResult)
  }

  // Custom logic: Admin can create for other users
  if (authResult.user?.role === 'admin' && body.userId) {
    task.userId = body.userId
  } else {
    task.userId = authResult.user!.id
  }

  // ... rest of implementation
  const response = createApiResponse(data, { created: true }, 201)
  return addCorsHeaders(response)
})

When to use: Complex validation, admin-level operations, external integrations.

3. Core Endpoints

System endpoints that cannot be overridden.

/api/v1/users - User management
/api/v1/api-keys - API key management
/api/v1/auth - Authentication

Input Validation

import * as z from 'zod'

const CreateProductSchema = z.object({
  title: z.string().min(1).max(255),
  price: z.number().positive(),
  status: z.enum(['active', 'inactive']).default('active'),
})

export const POST = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
  try {
    const body = CreateProductSchema.parse(await req.json())
    // Validated body ready to use
  } catch (error) {
    if (error instanceof z.ZodError) {
      const response = createApiError('Validation error', 400, error.issues, 'VALIDATION_ERROR')
      return addCorsHeaders(response)
    }
    throw error
  }
})

Scripts

Scaffold New Endpoint

# Basic endpoint
python .claude/skills/nextjs-api-development/scripts/scaffold-endpoint.py \
  --name products \
  --methods GET,POST \
  --auth required

# With [id] route for single resource operations
python .claude/skills/nextjs-api-development/scripts/scaffold-endpoint.py \
  --name products \
  --methods GET,POST \
  --auth required \
  --with-id

# Preview without creating files
python .claude/skills/nextjs-api-development/scripts/scaffold-endpoint.py \
  --name products \
  --dry-run

Generate CRUD Tests

# Generate test file only
python .claude/skills/nextjs-api-development/scripts/generate-crud-tests.py \
  --entity products

# Also generate API Controller
python .claude/skills/nextjs-api-development/scripts/generate-crud-tests.py \
  --entity products \
  --with-controller

# Preview
python .claude/skills/nextjs-api-development/scripts/generate-crud-tests.py \
  --entity products \
  --dry-run

Validate API Structure

python .claude/skills/nextjs-api-development/scripts/validate-api.py \
  --path app/api/v1/

# Strict mode (exit with error if violations found)
python .claude/skills/nextjs-api-development/scripts/validate-api.py \
  --path app/api/v1/ \
  --strict

Testing Pattern

Tests use API Controllers that extend BaseAPIController:

// In test file
const ProductsAPIController = require('../../../src/controllers/ProductsAPIController.js')

describe('Products API - CRUD Operations', {
  tags: ['@api', '@feat-products', '@crud', '@regression']
}, () => {
  let productsAPI: any

  const SUPERADMIN_API_KEY = Cypress.env('SUPERADMIN_API_KEY')
  const TEAM_ID = Cypress.env('TEAM_ID')

  before(() => {
    productsAPI = new ProductsAPIController(BASE_URL, SUPERADMIN_API_KEY, TEAM_ID)
  })

  it('should list products', () => {
    productsAPI.getProducts().then((response: any) => {
      productsAPI.validateSuccessResponse(response, 200)
      expect(response.body.data).to.be.an('array')
    })
  })
})

Security Best Practices

SQL Injection Prevention

RLS routing (beta.167): queryWithRLS(..., userId) runs on the app pool (RLS evaluated). The bare query()/queryOne() family routes to the service pool (bypass) — never use it for a user-scoped read. See the rls-enforcement skill for the service-pool model and the LIST/READ fail-closed enforcement now applied in the generic handler.

// ✅ CORRECT - Parameterized queries with queryWithRLS
const result = await queryWithRLS(
  `SELECT * FROM products WHERE "userId" = $1 AND status = $2 LIMIT $3`,
  [userId, status, limit],
  authResult.user!.id
)

// ❌ NEVER - String concatenation
const query = `SELECT * FROM products WHERE userId = '${userId}'`

Anti-Patterns

// ❌ NEVER: Use export async function instead of withApiLogging
export async function GET(request: NextRequest) { }

// ❌ NEVER: Return response without addCorsHeaders
return createApiResponse(data)

// ❌ NEVER: Use raw NextResponse.json
return NextResponse.json({ data })

// ❌ NEVER: Skip authentication
export async function GET(request: NextRequest) {
  const data = await db.query('SELECT * FROM products')
  return createApiResponse(data)
}

// ✅ CORRECT: Full pattern
export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
  const authResult = await authenticateRequest(req, { requiredScope: 'products:read' })
  // ...
  const response = createApiResponse(data)
  return addCorsHeaders(response)
})

nextjs-api-development

About