Part 1: Introduction to REST APIs and HTTP Fundamentals

My Journey into REST APIs

Five years ago, I built my first microservice—a simple user management system. I thought creating APIs meant "just return JSON from endpoints." My first production API had no structure: endpoints like /getUserData, /update_user_info, and /deleteUserRecord mixed conventions. Response formats varied—sometimes {data: {...}}, sometimes just {...}. HTTP status codes? Everything returned 200, even errors.

When the team grew to 5 developers, chaos ensued. Nobody could predict endpoint behavior. Integration took hours of debugging. That's when I learned REST principles aren't optional—they're essential for building maintainable, scalable APIs.

This series documents what I learned building production REST APIs that now handle millions of requests daily.

What is REST?

REST (Representational State Transfer) is an architectural style for designing networked applications. Created by Roy Fielding in his 2000 doctoral dissertation, REST defines principles for creating scalable web services.

Key Concept: Resources

In REST, everything is a resource—an entity or object in your system. Resources are identified by URLs and manipulated using standard HTTP methods.

Examples from my e-commerce microservices:

User: /api/users/123
Product: /api/products/456
Order: /api/orders/789
Cart: /api/carts/user-123

HTTP Fundamentals

Before diving into REST, you need to understand HTTP—the protocol REST builds upon.

HTTP Methods (Verbs)

From my production APIs, here's how I use each HTTP method:

1. GET - Retrieve Data

// src/controllers/user-controller.ts
import { Request, Response } from 'express';
import { UserService } from '../services/user-service';

export class UserController {
  constructor(private readonly userService: UserService) {}

  // GET /api/users - List all users
  async getAllUsers(req: Request, res: Response): Promise<void> {
    const users = await this.userService.findAll();
    res.status(200).json({
      success: true,
      data: users,
      count: users.length,
    });
  }

  // GET /api/users/:id - Get specific user
  async getUserById(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const user = await this.userService.findById(id);
    
    if (!user) {
      res.status(404).json({
        success: false,
        error: 'User not found',
      });
      return;
    }
    
    res.status(200).json({
      success: true,
      data: user,
    });
  }

  // GET /api/users?role=admin&status=active - Filter users
  async getFilteredUsers(req: Request, res: Response): Promise<void> {
    const { role, status } = req.query;
    
    const users = await this.userService.findByFilters({
      role: role as string,
      status: status as string,
    });
    
    res.status(200).json({
      success: true,
      data: users,
      count: users.length,
      filters: { role, status },
    });
  }
}

Characteristics:

Safe: Doesn't modify data
Idempotent: Multiple identical requests produce same result
Cacheable: Responses can be cached

2. POST - Create New Resource

// src/controllers/product-controller.ts
export class ProductController {
  constructor(private readonly productService: ProductService) {}

  // POST /api/products - Create new product
  async createProduct(req: Request, res: Response): Promise<void> {
    const { name, description, price, categoryId } = req.body;
    
    // Validation
    if (!name || !price) {
      res.status(400).json({
        success: false,
        error: 'Name and price are required',
      });
      return;
    }
    
    const product = await this.productService.create({
      name,
      description,
      price,
      categoryId,
    });
    
    res.status(201).json({
      success: true,
      data: product,
      message: 'Product created successfully',
    });
  }
}

Characteristics:

Not safe: Modifies data
Not idempotent: Multiple requests create multiple resources
Returns 201 Created on success

3. PUT - Replace Entire Resource

// src/controllers/product-controller.ts
export class ProductController {
  // PUT /api/products/:id - Replace entire product
  async replaceProduct(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const { name, description, price, categoryId, stock } = req.body;
    
    // PUT requires ALL fields
    if (!name || !price || categoryId === undefined || stock === undefined) {
      res.status(400).json({
        success: false,
        error: 'All fields required for PUT operation',
      });
      return;
    }
    
    const product = await this.productService.replace(id, {
      name,
      description,
      price,
      categoryId,
      stock,
    });
    
    if (!product) {
      res.status(404).json({
        success: false,
        error: 'Product not found',
      });
      return;
    }
    
    res.status(200).json({
      success: true,
      data: product,
      message: 'Product replaced successfully',
    });
  }
}

Characteristics:

Not safe: Modifies data
Idempotent: Multiple identical requests produce same result
Replaces entire resource

4. PATCH - Partial Update

// src/controllers/product-controller.ts
export class ProductController {
  // PATCH /api/products/:id - Update specific fields
  async updateProduct(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const updates = req.body;
    
    // PATCH allows partial updates
    const product = await this.productService.update(id, updates);
    
    if (!product) {
      res.status(404).json({
        success: false,
        error: 'Product not found',
      });
      return;
    }
    
    res.status(200).json({
      success: true,
      data: product,
      message: 'Product updated successfully',
    });
  }
}

Real usage from my inventory service:

// PATCH /api/products/123
// Body: { "stock": 50 }  - Only update stock
// Body: { "price": 29.99, "stock": 100 }  - Update price and stock

Characteristics:

Not safe: Modifies data
Idempotent: Multiple identical requests produce same result
Updates only specified fields

5. DELETE - Remove Resource

// src/controllers/product-controller.ts
export class ProductController {
  // DELETE /api/products/:id - Delete product
  async deleteProduct(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    
    const deleted = await this.productService.delete(id);
    
    if (!deleted) {
      res.status(404).json({
        success: false,
        error: 'Product not found',
      });
      return;
    }
    
    res.status(204).send(); // 204 No Content - successful deletion
  }

  // Soft delete implementation (what I use in production)
  async softDeleteProduct(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    
    const product = await this.productService.softDelete(id);
    
    if (!product) {
      res.status(404).json({
        success: false,
        error: 'Product not found',
      });
      return;
    }
    
    res.status(200).json({
      success: true,
      message: 'Product deleted successfully',
      data: { id, deletedAt: product.deletedAt },
    });
  }
}

Characteristics:

Not safe: Modifies data
Idempotent: Multiple requests produce same result (resource stays deleted)
Returns 204 No Content or 200 OK

HTTP Status Codes

From managing production APIs, these are the codes I use most:

2xx Success

// src/middleware/response-handler.ts
export class ResponseHandler {
  // 200 OK - Request succeeded
  static ok(res: Response, data: any, message?: string) {
    return res.status(200).json({
      success: true,
      data,
      message,
    });
  }

  // 201 Created - New resource created
  static created(res: Response, data: any, message?: string) {
    return res.status(201).json({
      success: true,
      data,
      message: message || 'Resource created successfully',
    });
  }

  // 204 No Content - Success with no response body
  static noContent(res: Response) {
    return res.status(204).send();
  }
}

4xx Client Errors

export class ResponseHandler {
  // 400 Bad Request - Invalid request
  static badRequest(res: Response, error: string) {
    return res.status(400).json({
      success: false,
      error,
    });
  }

  // 401 Unauthorized - Authentication required
  static unauthorized(res: Response, error: string = 'Authentication required') {
    return res.status(401).json({
      success: false,
      error,
    });
  }

  // 403 Forbidden - Authenticated but not authorized
  static forbidden(res: Response, error: string = 'Access denied') {
    return res.status(403).json({
      success: false,
      error,
    });
  }

  // 404 Not Found - Resource doesn't exist
  static notFound(res: Response, error: string = 'Resource not found') {
    return res.status(404).json({
      success: false,
      error,
    });
  }

  // 409 Conflict - Request conflicts with current state
  static conflict(res: Response, error: string) {
    return res.status(409).json({
      success: false,
      error,
    });
  }

  // 422 Unprocessable Entity - Validation failed
  static unprocessableEntity(res: Response, errors: any[]) {
    return res.status(422).json({
      success: false,
      error: 'Validation failed',
      details: errors,
    });
  }
}

Real example from my user service:

// src/controllers/auth-controller.ts
export class AuthController {
  async register(req: Request, res: Response): Promise<void> {
    const { email, password, name } = req.body;
    
    // Check if user exists
    const existingUser = await this.userService.findByEmail(email);
    if (existingUser) {
      // 409 Conflict - Email already registered
      return ResponseHandler.conflict(res, 'Email already registered');
    }
    
    const user = await this.userService.create({ email, password, name });
    
    // 201 Created - New user successfully created
    return ResponseHandler.created(res, user, 'User registered successfully');
  }

  async login(req: Request, res: Response): Promise<void> {
    const { email, password } = req.body;
    
    const user = await this.userService.findByEmail(email);
    if (!user) {
      // 401 Unauthorized - Invalid credentials
      return ResponseHandler.unauthorized(res, 'Invalid email or password');
    }
    
    const validPassword = await this.userService.verifyPassword(password, user.password);
    if (!validPassword) {
      // 401 Unauthorized - Invalid credentials
      return ResponseHandler.unauthorized(res, 'Invalid email or password');
    }
    
    const token = this.jwtService.sign({ userId: user.id });
    
    // 200 OK - Login successful
    return ResponseHandler.ok(res, { token, user });
  }
}

5xx Server Errors

export class ResponseHandler {
  // 500 Internal Server Error - Unexpected error
  static internalError(res: Response, error?: string) {
    return res.status(500).json({
      success: false,
      error: error || 'Internal server error',
    });
  }

  // 503 Service Unavailable - Temporary unavailability
  static serviceUnavailable(res: Response, error: string) {
    return res.status(503).json({
      success: false,
      error,
    });
  }
}

Global error handler from my production setup:

// src/middleware/error-handler.ts
import { Request, Response, NextFunction } from 'express';

export class ErrorHandler {
  static handle(err: Error, req: Request, res: Response, next: NextFunction) {
    console.error('Error:', err);
    
    // Database connection errors
    if (err.message.includes('ECONNREFUSED')) {
      return ResponseHandler.serviceUnavailable(res, 'Database temporarily unavailable');
    }
    
    // Validation errors
    if (err.name === 'ValidationError') {
      return ResponseHandler.badRequest(res, err.message);
    }
    
    // Default to 500
    return ResponseHandler.internalError(res, 'An unexpected error occurred');
  }
}

HTTP Headers

Headers I use in every production API:

// src/middleware/headers-middleware.ts
import { Request, Response, NextFunction } from 'express';

export class HeadersMiddleware {
  static setCommonHeaders(req: Request, res: Response, next: NextFunction) {
    // Content type
    res.setHeader('Content-Type', 'application/json');
    
    // CORS headers
    res.setHeader('Access-Control-Allow-Origin', process.env.ALLOWED_ORIGIN || '*');
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    
    // Security headers
    res.setHeader('X-Content-Type-Options', 'nosniff');
    res.setHeader('X-Frame-Options', 'DENY');
    res.setHeader('X-XSS-Protection', '1; mode=block');
    
    // Cache control
    res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
    res.setHeader('Pragma', 'no-cache');
    res.setHeader('Expires', '0');
    
    next();
  }
}

Request headers I check:

// src/middleware/auth-middleware.ts
export class AuthMiddleware {
  static async authenticate(req: Request, res: Response, next: NextFunction) {
    // Check Authorization header
    const authHeader = req.headers.authorization;
    
    if (!authHeader) {
      return ResponseHandler.unauthorized(res, 'Authorization header missing');
    }
    
    // Expected format: "Bearer <token>"
    const [scheme, token] = authHeader.split(' ');
    
    if (scheme !== 'Bearer' || !token) {
      return ResponseHandler.unauthorized(res, 'Invalid authorization format');
    }
    
    try {
      const decoded = jwtService.verify(token);
      req.user = decoded;
      next();
    } catch (error) {
      return ResponseHandler.unauthorized(res, 'Invalid or expired token');
    }
  }
}

What Makes an API RESTful?

REST has six architectural constraints. Here's how I implement them:

1. Client-Server Architecture

Separation of concerns: Frontend (client) is separate from backend (server).

// My microservices architecture
// Frontend: React app (port 3000)
// Backend API: Express.js (port 4000)
// Database: PostgreSQL (port 5432)

// Frontend makes HTTP requests to backend
// Backend has no knowledge of frontend implementation

2. Stateless

Each request contains all information needed—no session stored on server.

// BAD: Stateful (don't do this)
let userSession = {};

app.post('/login', (req, res) => {
  const user = authenticateUser(req.body);
  userSession[user.id] = user; // Server stores session ❌
  res.json({ success: true });
});

app.get('/profile', (req, res) => {
  const user = userSession[req.body.userId]; // Relies on stored session ❌
  res.json({ user });
});

// GOOD: Stateless (what I use)
app.post('/login', async (req, res) => {
  const user = await authenticateUser(req.body);
  const token = jwt.sign({ userId: user.id }, SECRET); // Generate token ✅
  res.json({ success: true, token });
});

app.get('/profile', authenticateMiddleware, async (req, res) => {
  // Token contains all needed info ✅
  const userId = req.user.userId;
  const user = await userService.findById(userId);
  res.json({ user });
});

3. Cacheable

Responses define whether they can be cached.

// src/controllers/product-controller.ts
export class ProductController {
  async getPublicProducts(req: Request, res: Response): Promise<void> {
    const products = await this.productService.findPublic();
    
    // Cache for 5 minutes
    res.setHeader('Cache-Control', 'public, max-age=300');
    res.setHeader('ETag', generateETag(products));
    
    res.status(200).json({
      success: true,
      data: products,
    });
  }

  async getUserOrders(req: Request, res: Response): Promise<void> {
    const orders = await this.orderService.findByUser(req.user.userId);
    
    // Don't cache private data
    res.setHeader('Cache-Control', 'private, no-cache');
    
    res.status(200).json({
      success: true,
      data: orders,
    });
  }
}

4. Uniform Interface

Consistent resource identification and manipulation.

// My consistent API design pattern
// All resources follow same structure

// Users
GET    /api/users           - List users
GET    /api/users/:id       - Get user
POST   /api/users           - Create user
PUT    /api/users/:id       - Replace user
PATCH  /api/users/:id       - Update user
DELETE /api/users/:id       - Delete user

// Products
GET    /api/products        - List products
GET    /api/products/:id    - Get product
POST   /api/products        - Create product
PUT    /api/products/:id    - Replace product
PATCH  /api/products/:id    - Update product
DELETE /api/products/:id    - Delete product

// Orders (same pattern)
GET    /api/orders
GET    /api/orders/:id
POST   /api/orders
PATCH  /api/orders/:id
DELETE /api/orders/:id

5. Layered System

Client can't tell if connected to end server or intermediary.

// My production architecture has multiple layers:
// Client → Load Balancer → API Gateway → Microservice → Database

// Client doesn't know about internal architecture
// All requests go to: https://api.myapp.com

// Internal routing (invisible to client):
// https://api.myapp.com/users → user-service:4001
// https://api.myapp.com/products → product-service:4002
// https://api.myapp.com/orders → order-service:4003

6. Code on Demand (Optional)

Server can send executable code to client.

// Rarely used, but example:
app.get('/api/calculator', (req, res) => {
  res.json({
    data: { result: 42 },
    script: 'function display(result) { console.log(result); }', // Executable code
  });
});

REST API Pros and Cons

From 5 years building production REST APIs:

Pros ✅

1. Simplicity and Familiarity

Every developer knows HTTP. No new protocols to learn.
My junior developers were productive on day 1.

2. Stateless = Scalable

No server-side sessions = easy horizontal scaling
I run 10 identical API instances behind load balancer
Each handles ~1000 req/s = 10,000 total req/s

3. Cacheable

CDN caching reduced database load by 80%
Product catalog requests: 10,000/min → 2,000/min hit database

4. Tooling

Every language has HTTP libraries
Postman, Insomnia, curl for testing
Browser DevTools for debugging

5. Standard HTTP Methods

No custom protocols
GET, POST, PUT, DELETE - universally understood

Cons ❌

1. Over-fetching

// Problem: Client needs only user's name and email
// But endpoint returns everything
GET /api/users/123

Response:
{
  "id": "123",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "address": {...},        // ❌ Not needed
  "orderHistory": [...],   // ❌ Not needed (100+ orders)
  "preferences": {...},    // ❌ Not needed
  "metadata": {...}        // ❌ Not needed
}

// Transferred 50KB when client needed 100 bytes

2. Under-fetching (N+1 Problem)

// Problem: Need users and their orders
// Requires multiple requests

// Request 1: Get user
GET /api/users/123
// Response: { id: 123, name: "John" }

// Request 2: Get user's orders
GET /api/orders?userId=123
// Response: [{ id: 1, ... }, { id: 2, ... }]

// Request 3-N: Get product details for each order
GET /api/products/456  // For order 1
GET /api/products/789  // For order 2
// ...

// Total: 1 + 1 + N requests
// With 10 orders = 12 HTTP requests
// 12 × 50ms latency = 600ms minimum

My solution:

// Created composite endpoints for common use cases
GET /api/users/123/orders?include=products

Response:
{
  "user": { "id": 123, "name": "John" },
  "orders": [
    {
      "id": 1,
      "total": 99.99,
      "product": { "id": 456, "name": "Widget" }  // ✅ Included
    }
  ]
}
// 1 request instead of 12

3. No Real-time Updates

REST is request-response
Client must poll for updates:
- Poll every 5 seconds = wasted requests
- WebSockets better for real-time

My solution: Use WebSockets for notifications,
REST for CRUD operations

4. Versioning Challenges

// Breaking changes require versioning
// My API evolution:

// v1: Original design
GET /api/v1/users/123
Response: { "id": 123, "name": "John Doe" }

// v2: Split name into firstName/lastName
GET /api/v2/users/123
Response: { "id": 123, "firstName": "John", "lastName": "Doe" }

// Now maintaining 2 versions = 2× code

5. Limited Query Capabilities

Can't dynamically select fields
Can't filter complex relationships
Can't aggregate data flexibly

GraphQL better for complex queries

Common REST API Use Cases

From my production experience:

1. Mobile Apps

Perfect fit: CRUD operations, stateless, cacheable
My e-commerce app: Product catalog, cart, checkout

2. Web Applications

Great for SPAs (Single Page Applications)
React/Vue/Angular calling REST APIs

3. Microservices Communication

Service-to-service communication
My architecture: 12 microservices, all REST APIs

4. Public APIs

REST is standard for public APIs
Easy for third-party developers
My payment integration: Stripe, PayPal (both REST)

5. IoT Devices

Lightweight, simple protocol
My smart home project: Devices POST sensor data

Key Takeaways

REST uses HTTP methods (GET, POST, PUT, PATCH, DELETE) to manipulate resources
Resources are identified by URLs (/api/users/123)
HTTP status codes communicate operation results (200, 201, 400, 404, 500)
Stateless design enables scalability
Cacheable responses improve performance

Pros: Simple, scalable, cacheable, universal tooling Cons: Over/under-fetching, no real-time, versioning challenges

Best for: CRUD operations, mobile/web apps, microservices, public APIs

Next in series: RESTful Design Principles and Best Practices—learn how to design clean, maintainable REST APIs.

Understanding HTTP fundamentals is crucial before building REST APIs. Master these basics, and you'll build better APIs.

PreviousREST API 101 NextPart 2: RESTful Design Principles and Best Practices

Last updated 15 hours ago

hashtagMy Journey into REST APIs

hashtagWhat is REST?

hashtagKey Concept: Resources

hashtagHTTP Fundamentals

hashtagHTTP Methods (Verbs)

hashtag1. GET - Retrieve Data

hashtag2. POST - Create New Resource

hashtag3. PUT - Replace Entire Resource

hashtag4. PATCH - Partial Update

hashtag5. DELETE - Remove Resource

hashtagHTTP Status Codes

hashtag2xx Success

hashtag4xx Client Errors

hashtag5xx Server Errors

hashtagHTTP Headers

hashtagWhat Makes an API RESTful?

hashtag1. Client-Server Architecture

hashtag2. Stateless

hashtag3. Cacheable

hashtag4. Uniform Interface

hashtag5. Layered System

hashtag6. Code on Demand (Optional)

hashtagREST API Pros and Cons

hashtagPros ✅

hashtagCons ❌

hashtagCommon REST API Use Cases

hashtag1. Mobile Apps

hashtag2. Web Applications

hashtag3. Microservices Communication

hashtag4. Public APIs

hashtag5. IoT Devices

hashtagKey Takeaways

My Journey into REST APIs

What is REST?

Key Concept: Resources

HTTP Fundamentals

HTTP Methods (Verbs)

1. GET - Retrieve Data

2. POST - Create New Resource

3. PUT - Replace Entire Resource

4. PATCH - Partial Update

5. DELETE - Remove Resource

HTTP Status Codes

2xx Success

4xx Client Errors

5xx Server Errors

HTTP Headers

What Makes an API RESTful?

1. Client-Server Architecture

2. Stateless

3. Cacheable

4. Uniform Interface

5. Layered System

6. Code on Demand (Optional)

REST API Pros and Cons

Pros ✅

Cons ❌

Common REST API Use Cases

1. Mobile Apps

2. Web Applications

3. Microservices Communication

4. Public APIs

5. IoT Devices

Key Takeaways