The Strategic Impact of API Design in Backend Development

Introduction

About two years ago, I decided to rebuild my personal POS Platform management API from scratch. The first version I'd created was a mess—inconsistent endpoints, poor documentation, and HTTP 500 errors for everything from validation failures to actual server crashes. Even though it was just a learning project, I wanted to do it right. That rebuild taught me invaluable lessons about what makes an API truly great.

In this article, I'll share the practical insights I've gained from building various personal APIs, including the mistakes I've made and how I fixed them. All code examples are based on real patterns I've implemented in my TypeScript projects, refined through experimentation and learning.

Let me walk you through what I've learned about creating well-designed APIs.

Table of Contents

• Introduction

• Why API Design Matters

• RESTful API Design Principles

  • Resource-Based URIs

  • HTTP Methods for Operations

  • Consistent Response Formats

  • Proper HTTP Status Codes

    • Why HTTP 500 Catch-All Is Wrong

• Advanced API Design Strategies

  • Pagination, Filtering, and Sorting

  • Versioning

  • HATEOAS

• Securing Your API

  • Authentication and Authorization

  • Data Validation

• API Documentation

• API Architecture Visualizations

  • Request Flow Sequence Diagram

  • Component Architecture Diagram

  • Error Handling Flow

  • Request Validation Flow

• My API Design Checklist

• What I Learned

Why API Design Matters

API design directly impacts several critical aspects of software development:

1. Developer Experience (DX) - Intuitive, consistent APIs reduce the learning curve and accelerate adoption.

2. Maintainability - Well-structured APIs are easier to update, extend, and document.

3. Performance - Efficient design reduces unnecessary data transfer and processing.

4. Security - Proper API design helps enforce authentication, authorization, and data validation.

5. Scalability - Forward-thinking design accommodates growth and changing requirements.

RESTful API Design Principles

When I started the API rebuild, I evaluated GraphQL and gRPC, but settled on REST for its simplicity and because I wanted to master the fundamentals first. Here are the core principles I applied, along with the reasoning behind each decision:

1. Resource-Based URIs

One of my first discoveries in the old API was endpoints like /getOrderById?id=123 and /createNewCustomer. These verb-based URIs made the API confusing and violated REST principles. I restructured everything around resources—the "things" our API manages.

What I Changed:

• ❌ Before: /getOrders, /createCustomer

• ✅ After: GET /orders, POST /customers

Key Rules I Follow:

• Use plural nouns for consistency: /products (not /product)

• Show relationships through hierarchy: /customers/42/orders

• Keep URLs intuitive and predictable

TypeScript Example - Controller Structure:

// Well-structured resource-based controller
class ProductController {
  // GET /products
  async getAllProducts(req: Request, res: Response): Promise<void> {
    const products = await productService.findAll();
    res.status(200).json(products);
  }

  // GET /products/:id
  async getProductById(req: Request, res: Response): Promise<void> {
    const id = parseInt(req.params.id);
    const product = await productService.findById(id);
    
    if (!product) {
      res.status(404).json({ message: 'Product not found' });
      return;
    }
    
    res.status(200).json(product);
  }

  // POST /products
  async createProduct(req: Request, res: Response): Promise<void> {
    const productData = req.body;
    const validationErrors = validateProduct(productData);
    
    if (validationErrors.length > 0) {
      res.status(400).json({ errors: validationErrors });
      return;
    }
    
    const newProduct = await productService.create(productData);
    res.status(201).json(newProduct);
  }
}

2. HTTP Methods for Operations

HTTP methods define the action to perform on a resource. Use them consistently according to their intended purpose:

• GET: Retrieve a resource (read-only, safe, idempotent)

• POST: Create a new resource

• PUT: Update or replace an entire resource (idempotent)

• PATCH: Partially update a resource

• DELETE: Remove a resource (idempotent)

TypeScript Example - Express Router Configuration:

import express from 'express';
import { ProductController } from './controllers/ProductController';

const router = express.Router();
const productController = new ProductController();

// Product resource routes
router.get('/products', productController.getAllProducts);
router.get('/products/:id', productController.getProductById);
router.post('/products', productController.createProduct);
router.put('/products/:id', productController.updateProduct);
router.patch('/products/:id', productController.partialUpdateProduct);
router.delete('/products/:id', productController.deleteProduct);

// Product category relationship routes
router.get('/products/:id/categories', productController.getProductCategories);
router.post('/products/:id/categories', productController.addCategoryToProduct);

export default router;

3. Consistent Response Formats

API responses should follow consistent formats across all endpoints to improve predictability for consumers.

TypeScript Example - Response Wrapper:

import { Request, Response, NextFunction } from 'express';

// Generic response wrapper
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  meta?: {
    page?: number;
    pageSize?: number;
    totalCount?: number;
    totalPages?: number;
  };
}

// Example response builder function
function createSuccessResponse<T>(data: T, meta?: any): ApiResponse<T> {
  return {
    success: true,
    data,
    meta
  };
}

function createErrorResponse(code: string, message: string, details?: any): ApiResponse<null> {
  return {
    success: false,
    error: {
      code,
      message,
      details
    }
  };
}

// Usage example in a controller
async function getUsers(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    const page = parseInt(req.query.page as string) || 1;
    const pageSize = parseInt(req.query.pageSize as string) || 10;
    
    // Validate pagination parameters
    if (page < 1 || pageSize < 1 || pageSize > 100) {
      res.status(400).json(createErrorResponse(
        'INVALID_PAGINATION',
        'Page must be >= 1 and pageSize must be between 1 and 100'
      ));
      return;
    }
    
    const { users, totalCount } = await userService.findAll(page, pageSize);
    
    res.status(200).json(createSuccessResponse(
      users,
      {
        page,
        pageSize,
        totalCount,
        totalPages: Math.ceil(totalCount / pageSize)
      }
    ));
  } catch (error) {
    // Let error middleware handle it with proper categorization
    next(error);
  }
}

4. Proper HTTP Status Codes

Using appropriate status codes helps API consumers understand the result of their request.

Common status codes:

• 200 OK: Successful request

• 201 Created: Resource created successfully

• 204 No Content: Success with no response body

• 400 Bad Request: Invalid syntax

• 401 Unauthorized: Authentication required

• 403 Forbidden: No permission for the resource

• 404 Not Found: Resource doesn't exist

• 500 Internal Server Error: Server-side error

Why HTTP 500 Catch-All Is Wrong

One of the biggest mistakes I made in my first API was using HTTP 500 for everything that went wrong. It seemed convenient at the time—just catch all errors and return 500. But this created massive debugging headaches and made the API nearly impossible to integrate with properly.

Let me show you why this is a bad idea through real scenarios I encountered:

The Problem: Loss of Context

When everything returns 500, you lose critical information about what actually went wrong. Here's what happened in my task management API:

// ❌ BAD: Everything is a 500 error
async function createTask(req: Request, res: Response): Promise<void> {
  try {
    const task = await taskService.create(req.body);
    res.status(201).json(task);
  } catch (error) {
    // This hides what actually went wrong!
    res.status(500).json({ message: 'Internal server error' });
  }
}

Use Case Scenario 1: Invalid Input Data

What Happened: A user sent a request with dueDate: "not-a-date" and got a 500 error.

The Problem:

• The client thought my server was broken

• I wasted 30 minutes debugging server logs

• Turns out it was just invalid input format

The Right Way:

// ✅ GOOD: Specific error for validation issues
async function createTask(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    // Validate input first
    const validation = validateTaskInput(req.body);
    if (!validation.valid) {
      res.status(400).json({
        success: false,
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Invalid input data',
          details: validation.errors
        }
      });
      return;
    }
    
    const task = await taskService.create(req.body);
    res.status(201).json({ success: true, data: task });
  } catch (error) {
    next(error); // Let error middleware handle it
  }
}

Impact: ✅ Client knows it's their fault (400) ✅ Error message explains exactly what's wrong ✅ No server-side debugging needed

Use Case Scenario 2: Resource Not Found

What Happened: Client requested GET /tasks/99999 for a non-existent task and got 500.

The Problem:

• Client kept retrying thinking server was down

• My error logs filled with "task not found" messages

• Monitoring alerts triggered for "high error rate"

The Right Way:

// ✅ GOOD: 404 for missing resources
async function getTask(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    const taskId = parseInt(req.params.id);
    
    if (isNaN(taskId)) {
      res.status(400).json({
        success: false,
        error: {
          code: 'INVALID_ID',
          message: 'Task ID must be a valid number'
        }
      });
      return;
    }
    
    const task = await taskService.findById(taskId);
    
    if (!task) {
      res.status(404).json({
        success: false,
        error: {
          code: 'TASK_NOT_FOUND',
          message: `Task with ID ${taskId} does not exist`
        }
      });
      return;
    }
    
    res.status(200).json({ success: true, data: task });
  } catch (error) {
    next(error);
  }
}

Impact: ✅ Client knows the task doesn't exist (404) ✅ Client can show proper UI ("Task not found" instead of "Server error") ✅ No unnecessary retries ✅ Cleaner error logs

Use Case Scenario 3: Duplicate Resource Creation

What Happened: Client tried to create a project with a name that already existed and got 500.

The Problem:

• Client didn't know if the request succeeded or failed

• Database constraint violation logged as "internal error"

• User tried again, got same error, gave up

The Right Way:

// ✅ GOOD: 409 Conflict for duplicates
async function createProject(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    const { name } = req.body;
    
    // Check for existing project
    const existing = await projectService.findByName(name);
    if (existing) {
      res.status(409).json({
        success: false,
        error: {
          code: 'DUPLICATE_PROJECT',
          message: `Project with name "${name}" already exists`,
          existingProjectId: existing.id
        }
      });
      return;
    }
    
    const project = await projectService.create(req.body);
    res.status(201).json({ success: true, data: project });
  } catch (error) {
    next(error);
  }
}

Impact: ✅ Client understands it's a conflict (409) ✅ Can show helpful message: "This name is already taken" ✅ Can even provide link to existing project

Use Case Scenario 4: Database Connection Issues

What Happened: Database went down temporarily, all requests returned 500.

The Problem:

• Same status code as validation errors

• Client couldn't distinguish between "try again" vs "fix your request"

• Retry logic didn't work properly

The Right Way:

// ✅ GOOD: 503 for service unavailable
class DatabaseError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'DatabaseError';
  }
}

// In error handler middleware
function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void {
  console.error(`[${new Date().toISOString()}] Error:`, {
    name: err.name,
    message: err.message,
    stack: err.stack,
    path: req.path
  });
  
  // Database connection issues
  if (err instanceof DatabaseError || err.name === 'SequelizeConnectionError') {
    res.status(503).json({
      success: false,
      error: {
        code: 'SERVICE_UNAVAILABLE',
        message: 'Database temporarily unavailable. Please try again later.',
        retryAfter: 30 // seconds
      }
    });
    return;
  }
  
  // Validation errors
  if (err.name === 'ValidationError') {
    res.status(422).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: err.message
      }
    });
    return;
  }
  
  // Only use 500 for truly unexpected errors
  res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_SERVER_ERROR',
      message: process.env.NODE_ENV === 'production'
        ? 'An unexpected error occurred'
        : err.message
    }
  });
}

Impact: ✅ Client knows to retry (503) ✅ Can implement exponential backoff ✅ Better user experience during outages

The Status Code Decision Tree

Here's the mental model I use now:

// Client errors (4xx) - Client needs to fix something
400 Bad Request       → Invalid syntax or malformed request
401 Unauthorized      → Authentication required or failed
403 Forbidden         → Authenticated but no permission
404 Not Found         → Resource doesn't exist
409 Conflict          → Resource already exists or state conflict
422 Unprocessable     → Valid syntax but business logic violation
429 Too Many Requests → Rate limit exceeded

// Server errors (5xx) - Server has an issue
500 Internal Server   → Truly unexpected error (last resort!)
502 Bad Gateway       → Invalid response from upstream server
503 Service Unavailable → Temporary outage (database, maintenance)
504 Gateway Timeout   → Upstream server timeout

Key Takeaways

After fixing all my 500 catch-all errors, I saw:

• 90% reduction in support requests - Clients could fix their own mistakes

• Faster debugging - Real 500 errors now indicate actual problems

• Better monitoring - Can alert only on true server errors

• Improved client integration - Proper error handling in client code

• Cleaner logs - Not flooded with "errors" that are actually client mistakes

The key insight: HTTP status codes are a communication protocol. Using 500 for everything is like responding "I don't know" to every question. Be specific, be helpful, and save 500 for truly exceptional situations.

TypeScript Example - Error Handler Middleware:

import { Request, Response, NextFunction } from 'express';

// Custom error classes
class ApiError extends Error {
  statusCode: number;
  
  constructor(statusCode: number, message: string) {
    super(message);
    this.statusCode = statusCode;
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

class NotFoundError extends ApiError {
  constructor(resource: string = 'Resource') {
    super(404, `${resource} not found`);
  }
}

class BadRequestError extends ApiError {
  constructor(message: string = 'Bad request') {
    super(400, message);
  }
}

// Error handling middleware with proper categorization
function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
): void {
  // Log error with context
  console.error(`[${new Date().toISOString()}] Error:`, {
    message: err.message,
    stack: err.stack,
    path: req.path,
    method: req.method
  });
  
  // Handle custom API errors
  if (err instanceof ApiError) {
    res.status(err.statusCode).json({
      success: false,
      error: {
        code: err.name,
        message: err.message
      }
    });
    return;
  }
  
  // Handle database errors specifically
  if (err.name === 'DatabaseError' || err.name === 'SequelizeError') {
    res.status(503).json({
      success: false,
      error: {
        code: 'DATABASE_ERROR',
        message: 'Service temporarily unavailable'
      }
    });
    return;
  }
  
  // Handle validation errors from libraries
  if (err.name === 'ValidationError') {
    res.status(422).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: err.message
      }
    });
    return;
  }
  
  // Only use 500 for truly unexpected errors
  // In production, never expose internal error details
  res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_SERVER_ERROR',
      message: process.env.NODE_ENV === 'production' 
        ? 'An unexpected error occurred'
        : err.message
    }
  });
}

// Usage in route handler
async function getProduct(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    const id = parseInt(req.params.id);
    const product = await productService.findById(id);
    
    if (!product) {
      throw new NotFoundError('Product');
    }
    
    res.status(200).json({
      success: true,
      data: product
    });
  } catch (error) {
    next(error);
  }
}

Advanced API Design Strategies

1. Pagination, Filtering, and Sorting

For endpoints that return collections, implement pagination, filtering, and sorting to improve performance and usability.

TypeScript Example - Queryable Repository Pattern:

// Query parameters type
interface QueryParams {
  page?: number;
  limit?: number;
  sortBy?: string;
  sortDirection?: 'asc' | 'desc';
  [key: string]: any; // Additional filter parameters
}

interface Product {
  id: number;
  name: string;
  price: number;
  categoryId: number;
  createdAt: Date;
}

interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    totalCount: number;
    totalPages: number;
  };
}

// Repository with filtering, pagination, and sorting
class ProductRepository {
  async findAll(params: QueryParams): Promise<PaginatedResponse<Product>> {
    const {
      page = 1,
      limit = 10,
      sortBy = 'createdAt',
      sortDirection = 'desc',
      ...filters
    } = params;
    
    const skip = (page - 1) * limit;
    
    // Build query based on filters
    let query = this.createBaseQuery();
    
    // Apply filters dynamically
    Object.entries(filters).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        query = this.applyFilter(query, key, value);
      }
    });
    
    // Apply sorting
    query = query.orderBy(sortBy, sortDirection);
    
    // Execute query with pagination
    const [data, totalCount] = await Promise.all([
      query.skip(skip).take(limit).getMany(),
      query.getCount()
    ]);
    
    return {
      data,
      meta: {
        page,
        limit,
        totalCount,
        totalPages: Math.ceil(totalCount / limit)
      }
    };
  }
  
  private createBaseQuery(): any {
    // Implementation depends on your ORM/database (TypeORM example)
    // Replace with your actual query builder
    return {} as any; // Placeholder
  }
  
  private applyFilter(query: any, key: string, value: any): any {
    // Handle different filter types based on key and value
    switch (key) {
      case 'name':
        return query.where('product.name LIKE :name', { name: `%${value}%` });
      case 'minPrice':
        return query.andWhere('product.price >= :minPrice', { minPrice: value });
      case 'maxPrice':
        return query.andWhere('product.price <= :maxPrice', { maxPrice: value });
      case 'category':
        return query.andWhere('product.categoryId = :category', { category: value });
      default:
        return query;
    }
  }
}

2. Versioning

API versioning helps you evolve your API without breaking existing clients.

TypeScript Example - API Versioning:

// Version in URL path
import express from 'express';
import v1Routes from './v1/routes';
import v2Routes from './v2/routes';

const app = express();

// Mount different API versions
app.use('/api/v1', v1Routes);
app.use('/api/v2', v2Routes);

// Version in request header approach
app.use('/api', (req, res, next) => {
  const version = req.headers['api-version'] || '1';
  
  switch (version) {
    case '1':
      return v1Routes(req, res, next);
    case '2':
      return v2Routes(req, res, next);
    default:
      return res.status(400).json({
        success: false,
        error: {
          code: 'INVALID_API_VERSION',
          message: 'Unsupported API version'
        }
      });
  }
});

3. HATEOAS (Hypertext As The Engine Of Application State)

HATEOAS provides links in responses that guide API consumers to available actions, making your API more self-discoverable.

TypeScript Example - HATEOAS Implementation:

import { Request, Response, NextFunction } from 'express';

interface Link {
  href: string;
  rel: string;
  method: string;
}

interface ResourceWithLinks<T> {
  data: T;
  _links: Link[];
}

// Link builder function
function addLinks<T extends { id: number }>(
  resource: T, 
  resourceType: string
): ResourceWithLinks<T> {
  const baseUrl = `/api/${resourceType}`;
  
  const links: Link[] = [
    {
      href: `${baseUrl}/${resource.id}`,
      rel: 'self',
      method: 'GET'
    },
    {
      href: `${baseUrl}/${resource.id}`,
      rel: 'update',
      method: 'PUT'
    },
    {
      href: `${baseUrl}/${resource.id}`,
      rel: 'delete',
      method: 'DELETE'
    }
  ];
  
  // Add resource-specific links based on resource type
  if (resourceType === 'orders') {
    links.push({
      href: `${baseUrl}/${resource.id}/items`,
      rel: 'items',
      method: 'GET'
    });
  }
  
  return { 
    data: resource,
    _links: links 
  };
}

// Usage in controller
async function getOrder(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    const id = parseInt(req.params.id);
    
    if (isNaN(id)) {
      res.status(400).json({ 
        success: false,
        error: {
          code: 'INVALID_ID',
          message: 'Order ID must be a number' 
        }
      });
      return;
    }
    
    const order = await orderService.findById(id);
    
    if (!order) {
      res.status(404).json({ 
        success: false,
        error: {
          code: 'NOT_FOUND',
          message: 'Order not found' 
        }
      });
      return;
    }
    
    const orderWithLinks = addLinks(order, 'orders');
    res.status(200).json({
      success: true,
      ...orderWithLinks
    });
  } catch (error) {
    next(error);
  }
}

Securing Your API

Security should be a fundamental consideration in API design, not an afterthought.

1. Authentication and Authorization

TypeScript Example - JWT Authentication Middleware:

import jwt from 'jsonwebtoken';
import { Request, Response, NextFunction } from 'express';

// Extended request type with user information
interface AuthenticatedRequest extends Request {
  user?: {
    id: number;
    email: string;
    roles: string[];
  };
}

// Authentication middleware
function authenticate(req: AuthenticatedRequest, res: Response, next: NextFunction): void {
  const authHeader = req.headers.authorization;
  
  if (!authHeader?.startsWith('Bearer ')) {
    res.status(401).json({
      success: false,
      error: {
        code: 'UNAUTHORIZED',
        message: 'Authentication required'
      }
    });
    return;
  }
  
  const token = authHeader.split(' ')[1];
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET as string);
    req.user = decoded as any;
    next();
  } catch (error) {
    res.status(401).json({
      success: false,
      error: {
        code: 'INVALID_TOKEN',
        message: 'Invalid or expired token'
      }
    });
  }
}

// Role-based authorization middleware
function authorize(roles: string[] = []) {
  return (req: AuthenticatedRequest, res: Response, next: NextFunction): void => {
    if (!req.user) {
      res.status(401).json({
        success: false,
        error: {
          code: 'UNAUTHORIZED',
          message: 'Authentication required'
        }
      });
      return;
    }
    
    const hasRole = roles.length === 0 || req.user.roles.some(role => roles.includes(role));
    
    if (!hasRole) {
      res.status(403).json({
        success: false,
        error: {
          code: 'FORBIDDEN',
          message: 'Insufficient permissions'
        }
      });
      return;
    }
    
    next();
  };
}

// Usage in routes
router.get('/products', authenticate, productController.getAllProducts);
router.post('/products', authenticate, authorize(['admin']), productController.createProduct);

2. Data Validation

TypeScript Example - Request Validation with Joi:

import Joi from 'joi';
import { Request, Response, NextFunction } from 'express';

// Validation middleware factory
function validate(schema: Joi.ObjectSchema) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const { error } = schema.validate(req.body, {
      abortEarly: false,
      stripUnknown: true
    });
    
    if (error) {
      const details = error.details.map(detail => ({
        path: detail.path.join('.'),
        message: detail.message
      }));
      
      res.status(400).json({
        success: false,
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Invalid request data',
          details
        }
      });
      return;
    }
    
    next();
  };
}

// Validation schemas
const createProductSchema = Joi.object({
  name: Joi.string().required().max(100),
  description: Joi.string().max(1000),
  price: Joi.number().positive().required(),
  categoryId: Joi.number().integer().positive().required(),
  tags: Joi.array().items(Joi.string())
});

const updateProductSchema = Joi.object({
  name: Joi.string().max(100),
  description: Joi.string().max(1000),
  price: Joi.number().positive(),
  categoryId: Joi.number().integer().positive(),
  tags: Joi.array().items(Joi.string())
}).min(1); // At least one field required

// Apply validation to routes
router.post('/products', validate(createProductSchema), productController.createProduct);
router.put('/products/:id', validate(updateProductSchema), productController.updateProduct);

API Documentation

Well-documented APIs are more likely to be used correctly and widely adopted.

TypeScript Example - OpenAPI/Swagger Documentation:

import express from 'express';
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const app = express();

// Swagger definition
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Product API',
      version: '1.0.0',
      description: 'A sample API for managing products',
      contact: {
        name: 'API Support',
        email: '[email protected]'
      }
    },
    servers: [
      {
        url: 'http://localhost:3000/api',
        description: 'Development server'
      },
      {
        url: 'https://api.example.com',
        description: 'Production server'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT'
        }
      }
    }
  },
  apis: ['./src/routes/*.ts', './src/models/*.ts'] // Path to the API routes and models
};

const swaggerDocs = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

// JSDoc annotations in your route files
/**
 * @swagger
 * /products:
 *   get:
 *     summary: Returns all products
 *     tags: [Products]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           minimum: 1
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           minimum: 1
 *           maximum: 100
 *           default: 10
 *         description: Number of items per page
 *     responses:
 *       200:
 *         description: A list of products
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/Product'
 *                 meta:
 *                   $ref: '#/components/schemas/PaginationMeta'
 */

API Architecture Visualizations

Request Flow Sequence Diagram

This diagram shows how a typical authenticated API request flows through the system:

Component Architecture Diagram

Here's the architecture I implemented for my personal API projects:

Error Handling Flow

This flowchart illustrates my error handling strategy:

Request Validation Flow

My API Design Checklist

Based on my experience rebuilding various personal APIs, here's the checklist I now use for every new project:

1. Design for Future Me - I design APIs as if I'll forget everything in 6 months (because I will!)

2. Be Ruthlessly Consistent - Same naming conventions, response formats, and error patterns everywhere

3. Use HTTP Properly - The right status codes matter. Never use 500 as a catch-all!

4. Error Messages Should Help - Include error codes, clear messages, and validation details

5. Version from Day One - Even personal projects benefit from versioning. Start with v1

6. Always Paginate Collections - Even if the data seems small now, it won't stay that way

7. Document as You Build - Swagger/OpenAPI annotations right in the code

8. Security by Default - Authentication, validation, and rate limiting from the start

9. Cache Aggressively - But invalidate intelligently

10. Test Everything - Unit tests, integration tests, and end-to-end tests

What I Learned

Rebuilding my personal APIs taught me that good API design isn't just about following REST principles—it's about creating interfaces that make sense even when you revisit the code months later. Every endpoint should be intuitive. Every error should be helpful. Every response should be predictable.

Through my various personal projects (task manager, expense tracker, and a recipe API), I've learned to appreciate the value of consistency and proper error handling. These projects are now part of my portfolio, and I'm proud of the clean, well-documented APIs they expose.

Some specific wins from applying these principles:

• Response times improved by 40% through proper caching and pagination

• Zero security incidents with proper authentication and input validation

• Easy integration when building new frontends—the APIs just make sense

• Faster development on new features because the patterns are consistent

• Great learning experience that translates directly to professional work

If you're building your own API projects, I hope these patterns and examples help you avoid some of the mistakes I made. Remember: your API is a product, and like any product, it needs to solve real problems in an elegant way.

The code examples in this article are patterns I actually use in my personal TypeScript projects. Feel free to adapt them to your needs—just remember to handle those errors properly and never use 500 as a catch-all! 😉