REST API Design: Resources, Endpoints, and Best Practices

REST API Fundamentals

• Core REST API design principles including resource modeling and URL structure
• Request and response format conventions that improve developer experience
• Status code usage patterns that convey meaningful information to API consumers
• Versioning strategies that allow evolution without breaking existing clients
• Documentation approaches that keep API docs accurate and up to date

// REST API route handler in Next.js
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const CreateResourceSchema = z.object({
  name: z.string().min(1).max(255),
  description: z.string().optional(),
  tags: z.array(z.string()).default([]),
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = CreateResourceSchema.parse(body);
    
    // Create resource in database
    const resource = await db.resource.create({
      data: validated,
    });
    
    return NextResponse.json(resource, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Implementing REST API with TypeScript

• Define request and response types that serve as living documentation
• Implement input validation with Zod schemas that infer TypeScript types automatically
• Use discriminated unions for type-safe error handling across API endpoints
• Generate API client code from your type definitions for frontend consumption
• Implement middleware with proper TypeScript types for request context

// Type-safe REST API with tRPC
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.context<Context>().create();

export const appRouter = t.router({
  getResource: t.procedure
    .input(z.object({ id: z.string().uuid() }))
    .query(async ({ input, ctx }) => {
      const resource = await ctx.db.resource.findUnique({
        where: { id: input.id },
      });
      if (!resource) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: 'Resource not found',
        });
      }
      return resource;
    }),
  
  listResources: t.procedure
    .input(z.object({
      page: z.number().min(1).default(1),
      limit: z.number().min(1).max(100).default(20),
      search: z.string().optional(),
    }))
    .query(async ({ input, ctx }) => {
      const { page, limit, search } = input;
      const offset = (page - 1) * limit;
      return ctx.db.resource.findMany({
        where: search ? { name: { contains: search } } : undefined,
        skip: offset,
        take: limit,
      });
    }),
});

REST API Security and Authentication

• Implement JWT-based authentication with proper token rotation and revocation
• Design authorization middleware that enforces role-based access control
• Add rate limiting to prevent abuse and ensure fair resource allocation
• Validate and sanitize all input data to prevent injection attacks
• Configure CORS, CSP, and other security headers for API endpoints
• Implement API key management for third-party integrations

REST API Performance Optimization

• Implement HTTP caching with proper Cache-Control headers and ETags
• Use database query optimization to reduce API response times
• Enable response compression with gzip or Brotli for smaller payloads
• Implement pagination, filtering, and field selection to reduce data transfer
• Set up connection pooling for database and external service connections
• Use CDN and edge caching for frequently accessed API responses

Testing and Documenting REST API

• Write unit tests for API route handlers and business logic functions
• Create integration tests that verify database queries and external service calls
• Implement contract testing to catch breaking changes before they reach production
• Generate OpenAPI documentation from your TypeScript types automatically
• Set up API monitoring that tracks response times and error rates in production

Frequently Asked Questions

Related Articles