API Designing

API Designing

Design consistent RESTful APIs for this Next.js application.

Process

1. Identify resources - What entities does the API manage?
2. Define operations - CRUD and custom actions
3. Design endpoints - URL structure and methods
4. Specify schemas - Request/response formats
5. Plan error handling - Consistent error responses

RESTful Conventions

URL Structure

/api/[resource]              # Collection
/api/[resource]/[id]         # Individual resource
/api/[resource]/[id]/[sub]   # Nested resource

HTTP Methods

Existing Project Patterns

Admin routes follow this structure:

/admin/api/articles          GET (list), POST (create)
/admin/api/articles/[id]     GET, PUT, DELETE
/admin/api/tags              GET, POST
/admin/api/media             GET, POST
/admin/api/users             GET, POST
/admin/api/users/[id]/approve POST (action)

Request Schemas

List Endpoints (GET collection)

Query parameters:

?page=1              # Pagination
?limit=10            # Items per page
?sort=created_at     # Sort field
?order=desc          # Sort direction
?status=published    # Filtering
?search=query        # Text search

Create/Update (POST/PUT)

// Request body
{
  title: string;
  body: string;
  slug?: string;      // Optional, auto-generate if missing
  published?: boolean;
  media_id?: number;
}

Response Schemas

Success Responses

Single resource:

{
  success: true,
  data: {
    id: number;
    title: string;
    // ... resource fields
  }
}

Collection:

{
  success: true,
  data: Resource[],
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  }
}

Action result:

{
  success: true,
  message: "Article published successfully"
}

Error Responses

// 400 Bad Request - Validation error
{
  success: false,
  error: "Validation failed",
  details: {
    title: "Title is required",
    slug: "Slug already exists"
  }
}

// 401 Unauthorized
{
  success: false,
  error: "Authentication required"
}

// 403 Forbidden
{
  success: false,
  error: "Admin access required"
}

// 404 Not Found
{
  success: false,
  error: "Article not found"
}

// 500 Internal Server Error
{
  success: false,
  error: "An unexpected error occurred"
}

Implementation Pattern

// src/app/admin/api/[resource]/route.ts
import { NextRequest, NextResponse } from "next/server";
import { requireEditor } from "@/lib/api-auth";
import { getDb } from "@/lib/db";

export async function GET(request: NextRequest) {
  const auth = await requireEditor();
  if (!auth.authorized) return auth.response;

  try {
    const db = await getDb();
    const { searchParams } = new URL(request.url);

    const page = parseInt(searchParams.get("page") || "1");
    const limit = parseInt(searchParams.get("limit") || "10");
    const offset = (page - 1) * limit;

    const items = await db.prepare(`
      SELECT * FROM resources
      ORDER BY created_at DESC
      LIMIT ? OFFSET ?
    `).bind(limit, offset).all();

    const { total } = await db.prepare(`
      SELECT COUNT(*) as total FROM resources
    `).first();

    return NextResponse.json({
      success: true,
      data: items.results,
      pagination: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit),
      },
    });
  } catch (error) {
    console.error("API error:", error);
    return NextResponse.json(
      { success: false, error: "Failed to fetch resources" },
      { status: 500 }
    );
  }
}

Validation

Validate at API boundaries:

function validateArticle(data: unknown): { valid: boolean; errors?: Record<string, string> } {
  const errors: Record<string, string> = {};

  if (!data || typeof data !== 'object') {
    return { valid: false, errors: { _: 'Invalid request body' } };
  }

  const { title, body, slug } = data as Record<string, unknown>;

  if (!title || typeof title !== 'string') {
    errors.title = 'Title is required';
  }
  if (!body || typeof body !== 'string') {
    errors.body = 'Body is required';
  }
  if (slug && typeof slug !== 'string') {
    errors.slug = 'Slug must be a string';
  }

  return Object.keys(errors).length ? { valid: false, errors } : { valid: true };
}

Output

Provide API design deliverables:

1. Endpoint specifications (URL, method, auth)
2. Request schema (body, query params)
3. Response schema (success, error)
4. Example implementation code