API Design - REST & GraphQL

Design consistent, intuitive APIs that scale

---

When to Use This Skill

Use this skill when:

• Designing new API endpoints (REST or GraphQL)
• Creating HTTP routes and handlers
• Implementing pagination, filtering, or sorting
• Versioning APIs for backward compatibility
• Handling API errors and validation
• Designing GraphQL schemas and resolvers
• Optimizing API performance (N+1 queries, caching)

Don't use this skill for:

• Frontend-only work with no API involvement
• Direct database queries without an API layer
• Internal function calls (not exposed as API)

---

Critical Patterns

Pattern 1: HTTP Methods and Status Codes

When: Building RESTful endpoints

Good:

// Correct HTTP methods and status codes
export async function GET(request: Request) {
  const users = await db.user.findMany();
  return NextResponse.json(users, { status: 200 });
}

export async function POST(request: Request) {
  const body = await request.json();

  if (!body.email || !body.name) {
    return NextResponse.json(
      { error: 'Email and name are required' },
      { status: 400 }  // Bad Request
    );
  }

  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 });  // Created
}

export async function DELETE(request: Request) {
  await db.user.delete({ where: { id: '123' } });
  return new Response(null, { status: 204 });  // No Content
}

Bad:

// ❌ Wrong: Using POST for everything
export async function POST(request: Request) {
  const { action, userId } = await request.json();

  if (action === 'get') {
    const user = await db.user.findUnique({ where: { id: userId } });
    return NextResponse.json(user);  // Should be GET
  }

  if (action === 'delete') {
    await db.user.delete({ where: { id: userId } });
    return NextResponse.json({ success: true });  // Should be DELETE
  }
}

// ❌ Wrong: Always returning 200
export async function GET(request: Request) {
  const user = await db.user.findUnique({ where: { id: '999' } });
  if (!user) {
    return NextResponse.json({ error: 'Not found' }, { status: 200 });  // Should be 404
  }
  return NextResponse.json(user);
}

Why: Correct HTTP methods and status codes make APIs predictable and RESTful. Clients can rely on standard semantics.

HTTP Methods Quick Reference:

GET     - Retrieve (Safe, Idempotent, Cacheable)
POST    - Create (Not safe, Not idempotent)
PUT     - Replace entire resource (Not safe, Idempotent)
PATCH   - Partial update (Not safe, Usually idempotent)
DELETE  - Remove (Not safe, Idempotent)

Status Codes Quick Reference:

2xx Success:
  200 OK            - Successful GET, PUT, PATCH, DELETE
  201 Created       - Successful POST (resource created)
  204 No Content    - Successful DELETE (no response body)

4xx Client Errors:
  400 Bad Request   - Invalid request data
  401 Unauthorized  - Authentication required
  403 Forbidden     - Authenticated but not authorized
  404 Not Found     - Resource doesn't exist
  409 Conflict      - Resource conflict (duplicate)
  422 Unprocessable - Validation errors

5xx Server Errors:
  500 Internal      - Unexpected server error
  503 Unavailable   - Server temporarily unavailable

---

Pattern 2: Resource Naming and Nesting

When: Designing API URL structure

Good:

// ✅ Use nouns, not verbs
GET /api/users
POST /api/users
GET /api/users/123
DELETE /api/users/123

// ✅ Plural nouns for collections
GET /api/products
GET /api/orders

// ✅ Nested resources (max 2 levels)
GET /api/users/123/posts
POST /api/users/123/posts
GET /api/users/123/posts/456

Bad:

// ❌ Wrong: Verbs in URLs
GET /api/getUsers
POST /api/createUser
DELETE /api/deleteUser/123

// ❌ Wrong: Singular for collections
GET /api/user
GET /api/product

// ❌ Wrong: Too deeply nested (3+ levels)
GET /api/users/123/posts/456/comments/789/likes

Why: Nouns represent resources, verbs are implied by HTTP methods. Avoid deep nesting to keep URLs simple and predictable.

Nested Resources Pattern:

GET /api/users/123/posts           - Get all posts by user 123
GET /api/users/123/posts/456       - Get specific post by user 123
POST /api/users/123/posts          - Create post for user 123

// ⚠️ For deep relationships, use query params instead:
GET /api/comments?postId=456
GET /api/likes?commentId=789

---

Pattern 3: Pagination

When: Returning large collections

Good - Cursor-based (recommended for large datasets):

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const cursor = searchParams.get('cursor');
  const limit = parseInt(searchParams.get('limit') || '20');

  const users = await db.user.findMany({
    take: limit + 1,
    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
    orderBy: { id: 'asc' },
  });

  const hasMore = users.length > limit;
  const data = hasMore ? users.slice(0, -1) : users;

  return NextResponse.json({
    data,
    pagination: {
      nextCursor: hasMore ? data[data.length - 1].id : null,
      hasMore,
    },
  });
}

Good - Offset-based (simpler, for admin panels):

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const page = parseInt(searchParams.get('page') || '1');
  const limit = parseInt(searchParams.get('limit') || '20');

  const [users, total] = await Promise.all([
    db.user.findMany({
      skip: (page - 1) * limit,
      take: limit,
    }),
    db.user.count(),
  ]);

  return NextResponse.json({
    data: users,
    pagination: {
      page,
      limit,
      total,
      totalPages: Math.ceil(total / limit),
    },
  });
}

Bad:

// ❌ No pagination - returns all records
export async function GET() {
  const users = await db.user.findMany();  // Could be millions!
  return NextResponse.json(users);
}

Why: Pagination prevents performance issues and timeouts. Cursor-based is more efficient for large datasets, offset-based is simpler for small datasets.

---

Pattern 4: API Versioning

When: Making breaking changes to existing APIs

Good - URL versioning (most explicit):

GET /api/v1/users
GET /api/v2/users

// app/api/v1/users/route.ts
export async function GET() {
  const users = await db.user.findMany();
  return NextResponse.json(users);  // Old format
}

// app/api/v2/users/route.ts
export async function GET() {
  const users = await db.user.findMany({
    include: { profile: true },  // New: Include related data
  });
  return NextResponse.json(users);
}

Breaking vs Non-Breaking Changes:

// ✅ Non-breaking (no version bump needed):
// - Add new endpoint
// - Add optional field to request
// - Add new field to response

// ❌ Breaking (requires new version):
// - Remove endpoint
// - Remove field from response
// - Rename field
// - Change field type
// - Make optional field required

Why: Versioning allows backward compatibility while evolving the API. Existing clients continue working while new clients use improved versions.

---

Pattern 5: Consistent Error Handling

When: Handling errors and validation

Good:

interface ApiError {
  code: string;
  message: string;
  details?: Array<{ field: string; message: string }>;
}

function errorResponse(status: number, error: ApiError) {
  return NextResponse.json({ error }, { status });
}

export async function POST(request: Request) {
  try {
    const body = await request.json();

    const errors = validateUser(body);
    if (errors.length > 0) {
      return errorResponse(400, {
        code: 'VALIDATION_ERROR',
        message: 'Invalid input data',
        details: errors,
      });
    }

    const user = await db.user.create({ data: body });
    return NextResponse.json(user, { status: 201 });
  } catch (error) {
    if (error.code === 'P2002') {
      return errorResponse(409, {
        code: 'DUPLICATE_EMAIL',
        message: 'Email already exists',
      });
    }

    return errorResponse(500, {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred',
    });
  }
}

Bad:

// ❌ Inconsistent error formats
export async function POST(request: Request) {
  try {
    const body = await request.json();

    if (!body.email) {
      return NextResponse.json('Email required');  // Plain string
    }

    const user = await db.user.create({ data: body });
    return NextResponse.json(user);
  } catch (error) {
    return NextResponse.json({
      message: error.message,  // Inconsistent format
      stack: error.stack,      // Leaks implementation details
    });
  }
}

Why: Consistent error format makes client error handling predictable. Never expose stack traces or internal details in production.

---

GraphQL Critical Patterns

Pattern 1: Schema Design with Types and Relationships

Good:

type User {
  id: ID!
  name: String!
  email: String!
  role: UserRole!
  posts: [Post!]!
  createdAt: DateTime!
}

enum UserRole {
  ADMIN
  USER
  GUEST
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  published: Boolean!
}

type Query {
  user(id: ID!): User
  users(limit: Int, cursor: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
}

input CreateUserInput {
  name: String!
  email: String!
  role: UserRole
}

Why: Clear types, non-null fields (the ! suffix), and input types make the API self-documenting and type-safe.

---

Pattern 2: Solving N+1 Queries with DataLoader

Problem:

// ❌ N+1 queries: 1 for users + N for posts
const resolvers = {
  User: {
    posts: async (parent, _args, context) => {
      return context.db.post.findMany({
        where: { authorId: parent.id },
      });
    },
  },
};
// Querying 100 users = 101 database queries!

Solution:

// ✅ DataLoader batches queries
import DataLoader from 'dataloader';

const postLoader = new DataLoader(async (userIds: readonly string[]) => {
  const posts = await db.post.findMany({
    where: { authorId: { in: [...userIds] } },
  });

  const postsByUserId = userIds.map(userId =>
    posts.filter(post => post.authorId === userId)
  );

  return postsByUserId;
});

const resolvers = {
  User: {
    posts: (parent, _args, context) => {
      return context.loaders.post.load(parent.id);
    },
  },
};
// Querying 100 users = 2 queries (users + batched posts)!

Why: DataLoader batches and caches database queries, solving the N+1 problem and dramatically improving performance.

---

Anti-Patterns

❌ Anti-Pattern 1: Exposing Database Structure Directly

Don't do this:

// ❌ API mirrors database exactly
GET /api/users
Response: {
  id: 123,
  password_hash: "bcrypt...",  // Exposing sensitive data!
  created_at: "2024-01-15",
  internal_notes: "VIP customer"
}

Do this instead:

// ✅ API has its own contract
GET /api/users/123
Response: {
  id: 123,
  name: "Alice",
  email: "alice@example.com",
  role: "admin",
  joinedAt: "2024-01-15T10:00:00Z"
}

// Server-side: Transform before sending
export async function GET(request: Request, { params }) {
  const user = await db.user.findUnique({ where: { id: params.id } });

  return NextResponse.json({
    id: user.id,
    name: user.name,
    email: user.email,
    role: user.role,
    joinedAt: user.createdAt,
  });
}

---

❌ Anti-Pattern 2: No Input Validation

Don't do this:

// ❌ Trusting all input
export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.user.create({ data: body });
  return NextResponse.json(user);
}

Do this instead:

// ✅ Validate all input
import { z } from 'zod';

const userSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  age: z.number().int().min(18).max(120),
});

export async function POST(request: Request) {
  const body = await request.json();

  const result = userSchema.safeParse(body);
  if (!result.success) {
    return NextResponse.json(
      { error: result.error.format() },
      { status: 400 }
    );
  }

  const user = await db.user.create({ data: result.data });
  return NextResponse.json(user, { status: 201 });
}

---

❌ Anti-Pattern 3: Ignoring Authentication

Don't do this:

// ❌ No auth checks
export async function DELETE(request: Request) {
  const { id } = await request.json();
  await db.user.delete({ where: { id } });
  return NextResponse.json({ success: true });
}

Do this instead:

// ✅ Check authentication and authorization
export async function DELETE(request: Request) {
  const session = await getSession(request);

  if (!session) {
    return new Response('Unauthorized', { status: 401 });
  }

  if (session.role !== 'ADMIN') {
    return new Response('Forbidden', { status: 403 });
  }

  const { id } = await request.json();
  await db.user.delete({ where: { id } });
  return new Response(null, { status: 204 });
}

---

Code Examples

Example 1: RESTful CRUD Endpoint

// app/api/users/[id]/route.ts
export async function GET(request: Request, { params }: { params: { id: string } }) {
  const user = await db.user.findUnique({ where: { id: params.id } });

  if (!user) {
    return new Response('User not found', { status: 404 });
  }

  return NextResponse.json(user);
}

export async function PATCH(request: Request, { params }: { params: { id: string } }) {
  const body = await request.json();
  const user = await db.user.update({
    where: { id: params.id },
    data: body,
  });

  return NextResponse.json(user);
}

Example 2: GraphQL Resolver with DataLoader

const resolvers = {
  Query: {
    users: async (_parent, { limit = 20, cursor }, context) => {
      const users = await context.db.user.findMany({
        take: limit + 1,
        ...(cursor && { cursor: { id: cursor }, skip: 1 }),
      });

      const hasMore = users.length > limit;
      const data = hasMore ? users.slice(0, -1) : users;

      return {
        edges: data.map(user => ({ node: user, cursor: user.id })),
        pageInfo: {
          hasNextPage: hasMore,
          endCursor: hasMore ? data[data.length - 1].id : null,
        },
      };
    },
  },
  User: {
    posts: (parent, _args, context) => {
      return context.loaders.posts.load(parent.id);
    },
  },
};

For comprehensive examples and detailed implementations, see the references/ folder.

---

Quick Reference

REST Checklist

• Use appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE)
• Return correct status codes (2xx, 4xx, 5xx)
• Use nouns for resources, not verbs
• Implement pagination for collections
• Version API for breaking changes
• Validate all input
• Return consistent error format
• Add authentication/authorization checks

GraphQL Checklist

• Design clear schema with types and relationships
• Use DataLoader to prevent N+1 queries
• Validate inputs with Zod or similar
• Return meaningful error codes in extensions
• Implement authentication via context
• Use connection pattern for pagination
• Keep mutations simple and focused

---

Progressive Disclosure

For detailed implementations, see:

• REST Patterns - Pagination, filtering, versioning, rate limiting, HATEOAS
• GraphQL Design - Resolvers, DataLoader, subscriptions, directives, input validation

---

References

• REST Patterns Reference
• GraphQL Design Reference
• GraphQL Documentation
• REST API Tutorial

---

Maintained by dsmj-ai-toolkit