Part 2: RESTful Design Principles and Best Practices

The Day My API Design Mattered

Two years into building microservices, our product team added 3 new developers. On their first day, they asked: "Where's the API documentation?" I opened Postman and showed them my endpoints:

POST /createUser
GET /getUserData?id=123
POST /update-product
DELETE /removeOrder
GET /api/v1/products/list
POST /products/create

They stared in confusion. "Which endpoints use /api/? Why mix camelCase and kebab-case? Is there a pattern?"

There wasn't. I'd built endpoints reactively—whatever worked at the moment. Each endpoint was a unique snowflake. Integration took days instead of hours.

That week, I learned RESTful design isn't about being "technically correct"—it's about building APIs other developers can understand without asking questions.

This article shares the design principles I now use on every API.

Resource Naming Conventions

The foundation of good REST API design is consistent resource naming.

Use Nouns, Not Verbs

Resources are things, not actions. HTTP methods provide the verbs.

❌ Bad (verb-based URLs):

POST /createUser
GET /getUser
POST /updateProduct
DELETE /removeOrder

✅ Good (noun-based URLs):

POST   /users          → Create user
GET    /users/:id      → Get user
PATCH  /products/:id   → Update product
DELETE /orders/:id     → Delete order

Use Plural Nouns

Collections should use plural names for consistency.

From my production APIs:

// src/routes/user-routes.ts
import { Router } from 'express';
import { UserController } from '../controllers/user-controller';

export class UserRoutes {
  static setup(router: Router, controller: UserController): void {
    // ✅ Plural: /users
    router.get('/users', controller.getAllUsers.bind(controller));
    router.get('/users/:id', controller.getUserById.bind(controller));
    router.post('/users', controller.createUser.bind(controller));
    router.patch('/users/:id', controller.updateUser.bind(controller));
    router.delete('/users/:id', controller.deleteUser.bind(controller));
  }
}

Consistency across all resources:

/users
/products
/orders
/categories
/reviews

Hierarchical Relationships

Use nested routes to show relationships between resources.

// src/routes/order-routes.ts
export class OrderRoutes {
  static setup(router: Router, controller: OrderController): void {
    // User's orders
    router.get('/users/:userId/orders', controller.getUserOrders.bind(controller));
    
    // Specific order for user
    router.get('/users/:userId/orders/:orderId', controller.getOrderById.bind(controller));
    
    // Order items (nested resource)
    router.get('/orders/:orderId/items', controller.getOrderItems.bind(controller));
    router.post('/orders/:orderId/items', controller.addOrderItem.bind(controller));
    router.delete('/orders/:orderId/items/:itemId', controller.removeOrderItem.bind(controller));
  }
}

Real examples from my e-commerce API:

GET /users/123/orders              → All orders for user 123
GET /users/123/orders/456          → Specific order 456 for user 123
GET /orders/456/items              → All items in order 456
GET /products/789/reviews          → All reviews for product 789
GET /categories/10/products        → All products in category 10

Avoid Deep Nesting

Limit nesting to 2-3 levels maximum. Deep nesting becomes unwieldy.

❌ Too deep:

GET /users/123/orders/456/items/789/product/details

✅ Better:

GET /orders/456/items/789

My rule: If the resource can be accessed independently, give it a top-level endpoint.

// Both patterns supported in my API
GET /users/123/orders              // List user's orders
GET /orders?userId=123             // Same result, flatter structure

GET /orders/456/items              // Order's items
GET /order-items?orderId=456       // Same result, independent resource

URL Structure Best Practices

Use Kebab-Case

Consistent casing improves readability.

❌ Inconsistent:

/userAccounts
/product-categories
/OrderItems

✅ Consistent (kebab-case):

/user-accounts
/product-categories
/order-items

My implementation:

// src/routes/index.ts
import { Router } from 'express';

export class ApiRoutes {
  static setup(): Router {
    const router = Router();
    
    // All routes use kebab-case
    router.use('/user-accounts', userAccountRoutes);
    router.use('/product-categories', productCategoryRoutes);
    router.use('/order-items', orderItemRoutes);
    router.use('/shopping-carts', shoppingCartRoutes);
    router.use('/payment-methods', paymentMethodRoutes);
    
    return router;
  }
}

Versioning

Always version your API from day one.

Three versioning strategies I've used:

1. URL Path Versioning (My Preferred Method)

// src/app.ts
import express from 'express';

const app = express();

// Version 1 routes
app.use('/api/v1/users', v1UserRoutes);
app.use('/api/v1/products', v1ProductRoutes);

// Version 2 routes (with breaking changes)
app.use('/api/v2/users', v2UserRoutes);
app.use('/api/v2/products', v2ProductRoutes);

Advantages:

• Clear and visible

• Easy to route to different codebases

• Cache-friendly

Example:

https://api.myapp.com/api/v1/users
https://api.myapp.com/api/v2/users

2. Header Versioning

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

export class VersionMiddleware {
  static extractVersion(req: Request, res: Response, next: NextFunction) {
    const version = req.headers['api-version'] || 'v1';
    req.apiVersion = version;
    next();
  }
}

// Usage
app.use(VersionMiddleware.extractVersion);

app.get('/users', (req, res) => {
  if (req.apiVersion === 'v2') {
    // V2 logic
    return res.json(getUsersV2());
  }
  // V1 logic (default)
  return res.json(getUsersV1());
});

Client request:

curl -H "API-Version: v2" https://api.myapp.com/users

3. Accept Header Versioning

// Request
Accept: application/vnd.myapp.v2+json

// Middleware
export class AcceptVersionMiddleware {
  static extractVersion(req: Request, res: Response, next: NextFunction) {
    const accept = req.headers.accept || '';
    const match = accept.match(/vnd\.myapp\.v(\d+)/);
    req.apiVersion = match ? `v${match[1]}` : 'v1';
    next();
  }
}

My production choice: URL path versioning—it's explicit and requires no header manipulation.

Query Parameters

Use query parameters for filtering, sorting, pagination, and field selection.

Filtering

// src/controllers/product-controller.ts
export class ProductController {
  async getProducts(req: Request, res: Response): Promise<void> {
    const {
      category,
      minPrice,
      maxPrice,
      inStock,
      brand,
    } = req.query;
    
    const filters: any = {};
    
    if (category) filters.category = category;
    if (brand) filters.brand = brand;
    if (inStock === 'true') filters.stock = { $gt: 0 };
    
    if (minPrice || maxPrice) {
      filters.price = {};
      if (minPrice) filters.price.$gte = parseFloat(minPrice as string);
      if (maxPrice) filters.price.$lte = parseFloat(maxPrice as string);
    }
    
    const products = await this.productService.find(filters);
    
    res.json({
      success: true,
      data: products,
      count: products.length,
      filters,
    });
  }
}

Real usage:

GET /products?category=electronics
GET /products?category=electronics&inStock=true
GET /products?minPrice=100&maxPrice=500
GET /products?brand=Apple&category=phones

Sorting

export class ProductController {
  async getProducts(req: Request, res: Response): Promise<void> {
    const { sortBy = 'createdAt', order = 'desc' } = req.query;
    
    // Validate sort fields
    const allowedSortFields = ['name', 'price', 'createdAt', 'popularity'];
    if (!allowedSortFields.includes(sortBy as string)) {
      return res.status(400).json({
        success: false,
        error: `Invalid sort field. Allowed: ${allowedSortFields.join(', ')}`,
      });
    }
    
    const sortOrder = order === 'asc' ? 1 : -1;
    
    const products = await this.productService.find({}, {
      sort: { [sortBy as string]: sortOrder },
    });
    
    res.json({
      success: true,
      data: products,
      meta: {
        sortBy,
        order,
      },
    });
  }
}

Usage:

GET /products?sortBy=price&order=asc      → Cheapest first
GET /products?sortBy=price&order=desc     → Most expensive first
GET /products?sortBy=popularity           → Most popular (desc default)

Pagination

Cursor-based pagination (my preferred method for large datasets):

// src/controllers/order-controller.ts
export class OrderController {
  async getOrders(req: Request, res: Response): Promise<void> {
    const {
      limit = '20',
      cursor,
    } = req.query;
    
    const limitNum = Math.min(parseInt(limit as string), 100); // Max 100
    
    const query: any = {};
    if (cursor) {
      // Cursor is base64-encoded ID of last item
      query._id = { $gt: Buffer.from(cursor as string, 'base64').toString() };
    }
    
    const orders = await this.orderService.find(query, {
      limit: limitNum + 1, // Fetch one extra to check if more exist
      sort: { _id: 1 },
    });
    
    const hasMore = orders.length > limitNum;
    const items = hasMore ? orders.slice(0, -1) : orders;
    
    const nextCursor = hasMore
      ? Buffer.from(items[items.length - 1]._id).toString('base64')
      : null;
    
    res.json({
      success: true,
      data: items,
      pagination: {
        limit: limitNum,
        hasMore,
        nextCursor,
      },
    });
  }
}

Usage:

GET /orders?limit=20                    → First page
GET /orders?limit=20&cursor=abc123      → Next page

Offset-based pagination (simpler, for small datasets):

export class ProductController {
  async getProducts(req: Request, res: Response): Promise<void> {
    const page = parseInt(req.query.page as string) || 1;
    const limit = parseInt(req.query.limit as string) || 20;
    
    const skip = (page - 1) * limit;
    
    const [products, total] = await Promise.all([
      this.productService.find({}, { skip, limit }),
      this.productService.count(),
    ]);
    
    const totalPages = Math.ceil(total / limit);
    
    res.json({
      success: true,
      data: products,
      pagination: {
        page,
        limit,
        total,
        totalPages,
        hasNext: page < totalPages,
        hasPrev: page > 1,
      },
    });
  }
}

Usage:

GET /products?page=1&limit=20
GET /products?page=2&limit=20

Field Selection (Sparse Fieldsets)

Allow clients to request only needed fields.

// src/controllers/user-controller.ts
export class UserController {
  async getUsers(req: Request, res: Response): Promise<void> {
    const { fields } = req.query;
    
    let projection: any = {};
    
    if (fields) {
      // Parse comma-separated fields: ?fields=id,name,email
      const fieldList = (fields as string).split(',');
      fieldList.forEach(field => {
        projection[field.trim()] = 1;
      });
    } else {
      // Default: exclude sensitive fields
      projection = { password: 0, resetToken: 0 };
    }
    
    const users = await this.userService.find({}, { projection });
    
    res.json({
      success: true,
      data: users,
    });
  }
}

Usage:

GET /users?fields=id,name,email         → Only these fields
GET /users                              → All fields except sensitive ones

HTTP Method Usage

Idempotency Matters

Understanding idempotency prevents bugs in production.

Idempotent methods (can be called multiple times safely):

• GET

• PUT

• DELETE

• HEAD

• OPTIONS

Non-idempotent method:

• POST

Real production example:

// src/controllers/order-controller.ts
export class OrderController {
  // POST is NOT idempotent - creates new order each time
  async createOrder(req: Request, res: Response): Promise<void> {
    const order = await this.orderService.create(req.body);
    
    res.status(201).json({
      success: true,
      data: order,
    });
  }
  
  // PUT is idempotent - same request always produces same result
  async updateOrderStatus(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const { status } = req.body;
    
    // Calling this 5 times with status="shipped" is safe
    // Order ends up in "shipped" status either way
    const order = await this.orderService.updateStatus(id, status);
    
    res.json({
      success: true,
      data: order,
    });
  }
  
  // DELETE is idempotent - deleting already-deleted resource is safe
  async cancelOrder(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    
    const order = await this.orderService.findById(id);
    
    if (!order) {
      // Already deleted/doesn't exist - still return success
      return res.status(204).send();
    }
    
    await this.orderService.delete(id);
    res.status(204).send();
  }
}

Why this matters:

Network issues cause request retries. If a client's POST request succeeds but the response is lost, they might retry—creating duplicate orders. My solution:

// Idempotency keys for POST requests
export class IdempotencyMiddleware {
  private static processedKeys = new Set<string>();
  
  static async enforce(req: Request, res: Response, next: NextFunction) {
    if (req.method !== 'POST') {
      return next();
    }
    
    const idempotencyKey = req.headers['idempotency-key'] as string;
    
    if (!idempotencyKey) {
      return res.status(400).json({
        success: false,
        error: 'Idempotency-Key header required for POST requests',
      });
    }
    
    // Check if we've processed this key
    if (this.processedKeys.has(idempotencyKey)) {
      return res.status(409).json({
        success: false,
        error: 'Request already processed',
      });
    }
    
    // Mark as processed
    this.processedKeys.add(idempotencyKey);
    
    // Clean up old keys (in production, use Redis with TTL)
    setTimeout(() => {
      this.processedKeys.delete(idempotencyKey);
    }, 24 * 60 * 60 * 1000); // 24 hours
    
    next();
  }
}

PUT vs PATCH

PUT: Replace entire resource PATCH: Update specific fields

// src/controllers/product-controller.ts
export class ProductController {
  // PUT - Must provide ALL fields
  async replaceProduct(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const { name, description, price, category, stock, sku } = req.body;
    
    // Validation: All fields required
    if (!name || !price || !category || stock === undefined || !sku) {
      return res.status(400).json({
        success: false,
        error: 'PUT requires all fields: name, price, category, stock, sku',
      });
    }
    
    const product = await this.productService.replace(id, {
      name,
      description,
      price,
      category,
      stock,
      sku,
    });
    
    res.json({ success: true, data: product });
  }
  
  // PATCH - Provide only fields to update
  async updateProduct(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const updates = req.body;
    
    // Only provided fields are updated
    const product = await this.productService.update(id, updates);
    
    res.json({ success: true, data: product });
  }
}

Real usage:

# PUT - Replace entire product
PUT /products/123
{
  "name": "New Widget",
  "description": "Updated description",
  "price": 49.99,
  "category": "electronics",
  "stock": 100,
  "sku": "WIDGET-001"
}

# PATCH - Update only price and stock
PATCH /products/123
{
  "price": 39.99,
  "stock": 150
}

My preference: PATCH for most updates. PUT rarely needed in practice.

Response Format Consistency

Every response follows the same structure in my APIs.

// src/types/api-response.ts
export interface ApiResponse<T = any> {
  success: boolean;
  data?: T;
  error?: string;
  errors?: string[];
  message?: string;
  meta?: {
    page?: number;
    limit?: number;
    total?: number;
    [key: string]: any;
  };
}

// src/utils/response-formatter.ts
export class ResponseFormatter {
  static success<T>(data: T, message?: string, meta?: any): ApiResponse<T> {
    return {
      success: true,
      data,
      ...(message && { message }),
      ...(meta && { meta }),
    };
  }
  
  static error(error: string, errors?: string[]): ApiResponse {
    return {
      success: false,
      error,
      ...(errors && { errors }),
    };
  }
}

All my endpoints use this format:

// Success response
{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe"
  },
  "message": "User created successfully"
}

// Error response
{
  "success": false,
  "error": "User not found"
}

// Validation errors
{
  "success": false,
  "error": "Validation failed",
  "errors": [
    "Email is required",
    "Password must be at least 8 characters"
  ]
}

// List with pagination
{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

HATEOAS (Hypermedia)

HATEOAS (Hypermedia as the Engine of Application State) includes links to related resources in responses.

Basic implementation:

// src/controllers/user-controller.ts
export class UserController {
  async getUserById(req: Request, res: Response): Promise<void> {
    const { id } = req.params;
    const user = await this.userService.findById(id);
    
    if (!user) {
      return res.status(404).json({
        success: false,
        error: 'User not found',
      });
    }
    
    res.json({
      success: true,
      data: user,
      links: {
        self: `/api/users/${id}`,
        orders: `/api/users/${id}/orders`,
        cart: `/api/users/${id}/cart`,
        preferences: `/api/users/${id}/preferences`,
      },
    });
  }
  
  async getUserOrders(req: Request, res: Response): Promise<void> {
    const { userId } = req.params;
    const orders = await this.orderService.findByUser(userId);
    
    res.json({
      success: true,
      data: orders.map(order => ({
        ...order,
        links: {
          self: `/api/orders/${order.id}`,
          items: `/api/orders/${order.id}/items`,
          user: `/api/users/${userId}`,
        },
      })),
      links: {
        self: `/api/users/${userId}/orders`,
        user: `/api/users/${userId}`,
      },
    });
  }
}

Response example:

{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "links": {
    "self": "/api/users/123",
    "orders": "/api/users/123/orders",
    "cart": "/api/users/123/cart",
    "preferences": "/api/users/123/preferences"
  }
}

Benefit: Clients discover available actions without hardcoding URLs.

Content Negotiation

Support multiple response formats when needed.

// src/middleware/content-negotiation.ts
export class ContentNegotiationMiddleware {
  static negotiate(req: Request, res: Response, next: NextFunction) {
    const accept = req.headers.accept || 'application/json';
    
    res.locals.responseFormat = 'json'; // Default
    
    if (accept.includes('application/xml')) {
      res.locals.responseFormat = 'xml';
    } else if (accept.includes('text/csv')) {
      res.locals.responseFormat = 'csv';
    }
    
    next();
  }
}

// Controller usage
export class ProductController {
  async getProducts(req: Request, res: Response): Promise<void> {
    const products = await this.productService.findAll();
    const format = res.locals.responseFormat;
    
    if (format === 'csv') {
      const csv = this.convertToCSV(products);
      res.setHeader('Content-Type', 'text/csv');
      res.setHeader('Content-Disposition', 'attachment; filename=products.csv');
      return res.send(csv);
    }
    
    if (format === 'xml') {
      const xml = this.convertToXML(products);
      res.setHeader('Content-Type', 'application/xml');
      return res.send(xml);
    }
    
    // Default: JSON
    res.json({ success: true, data: products });
  }
}

Key Takeaways

1. Use nouns, not verbs for resource URLs

2. Plural names for consistency (/users, not /user)

3. Nest resources to show relationships, but limit depth

4. Version from day one using URL path versioning

5. Query parameters for filtering, sorting, pagination

6. Consistent response format across all endpoints

7. Understand idempotency to handle retries safely

8. PATCH for updates, PUT rarely needed

9. Include metadata (pagination, filters) in responses

10. HATEOAS links help clients discover API capabilities

Next in series: Building REST APIs with Express.js and TypeScript—hands-on implementation of these principles.

---

Good API design is about consistency and predictability. Follow these principles, and your APIs will be a joy to work with.