Why RESTful APIs Still Matter

Representational State Transfer (REST) has been the de‑facto standard for web services for more than a decade. Its simplicity, reliance on standard HTTP verbs, and language‑agnostic nature make it ideal for micro‑service ecosystems, mobile back‑ends, and third‑party integrations.

While the core concepts of REST are straightforward, building an API that scales, stays secure, and remains easy to evolve requires disciplined engineering. This article distills the most critical best practices and demonstrates how to apply them in a realistic product‑catalog service.

Who Should Read This?

The guide targets developers with a basic understanding of HTTP and server‑side programming who want to elevate their API design from “just works” to “industry‑grade”.

---

1. Consistent Resource Modeling

1.1 Use Nouns, Not Verbs

RESTful endpoints describe resources, not actions. For a product catalog, the base URI should be /api/v1/products rather than /api/v1/getProducts.

1.2 Hierarchical Relationships

Sub‑resources reflect real‑world associations. Example:

GET /api/v1/products/{productId}/reviews POST /api/v1/products/{productId}/reviews

2. HTTP Verb Discipline

Verb	Safe?	Idempotent?	Typical Use
GET	✅	✅	Retrieve a representation
POST	❌	❌	Create a new resource
PUT	❌	✅	Replace an entire resource
PATCH	❌	✅	Partial update
DELETE	❌	✅	Remove a resource

Never overload a verb to perform unrelated tasks; keep each request semantically aligned with its HTTP method.

3. Status Codes & Error Payloads

Return the most specific HTTP status code. For validation failures use 422 Unprocessable Entity; for missing resources use 404 Not Found. Provide a machine‑readable error object:

{ "error": "ValidationFailed", "message": "Price must be a positive number.", "field": "price", "timestamp": "2026-02-28T12:34:56Z" }

4. Versioning Strategy

Hard‑wire the API version into the URL to avoid breaking existing clients:

GET /api/v1/products GET /api/v2/products?include=inventory

When moving to a new version, keep the old one operational for at least a migration window.

5. Pagination, Filtering, & Sorting

Large collections must be paginated. The Cursor‑Based approach scales better than offset pagination.

GET /api/v1/products?limit=20&cursor=eyJpZCI6MTAwfQ==

Support filtering via query parameters and allow sorting on indexed fields.

6. Security Essentials

• Enforce HTTPS everywhere.
• Authenticate using JWT or OAuth 2.0 Bearer tokens.
• Authorize at the resource level (e.g., role‑based access control).
• Implement rate limiting (e.g., 100 requests per minute per IP).
• Sanitize inputs to prevent injection attacks.

---

Overview of the Service

The sample implementation uses Node.js, Express, and PostgreSQL. It demonstrates the best practices discussed earlier, including clean routing, middleware for validation/authentication, and a layered architecture.

Architecture Diagram (Textual)

┌─────────────────────┐ │ API Gateway (NGINX) │ └───────▲───────▲───────┘ │ │ HTTPS│ Rate‑Limiting │ │ ┌───────▼───────▼───────┐ │ Express Application │ │ (Controller Layer) │ └───────▲───────▲───────┘ │ │ Validation Auth │ │ ┌───────▼───────▼───────┐ │ Service Layer │ │ (Business Logic) │ └───────▲───────▲───────┘ │ │ DB Access Caching │ │ ┌───────▼───────▼───────┐ │ PostgreSQL + Redis │ └───────────────────────┘

• API Gateway terminates TLS and applies global rate‑limiting.
• Controller Layer handles request/response mapping.
• Service Layer contains domain logic, keeping controllers thin.
• Data Access utilizes parameterised queries via node‑pg and optional Redis caching for read‑heavy endpoints.

Code Example - Project Skeleton

bash my-catalog-api/ ├─ src/ │ ├─ controllers/ │ │ └─ product.controller.ts │ ├─ services/ │ │ └─ product.service.ts │ ├─ routes/ │ │ └─ product.routes.ts │ ├─ middlewares/ │ │ ├─ auth.middleware.ts │ │ └─ validate.middleware.ts │ ├─ db/ │ │ └─ index.ts │ └─ app.ts ├─ .env ├─ package.

└─ tsconfig.json

Detailed Implementation

1. Database Layer (src/db/index.ts)

typescript import { Pool } from 'pg'; import dotenv from 'dotenv';

dotenv.config();

export const pool = new Pool({ connectionString: process.env.DATABASE_URL, ssl: { rejectUnauthorized: false } });

export const query = (text: string, params?: any[]) => pool.query(text, params);

2. Validation Middleware (src/middlewares/validate.middleware.ts)

typescript import { Request, Response, NextFunction } from 'express'; import { validationResult } from 'express-validator';

export const validate = (req: Request, res: Response, next: NextFunction) => { const errors = validationResult(req); if (!errors.isEmpty()) { return res.status(422).json({ error: 'ValidationFailed', details: errors.array() }); } next(); };

3. Authentication Middleware (src/middlewares/auth.middleware.ts)

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

declare global { namespace Express { interface Request { user?: any } } }

export const authenticate = (req: Request, res: Response, next: NextFunction) => { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { return res.sendStatus(401); } const token = authHeader.split(' ')[1]; try { const payload = jwt.verify(token, process.env.JWT_SECRET!); req.user = payload; next(); } catch (e) { return res.sendStatus(403); } };

4. Service Layer (src/services/product.service.ts)

typescript import { query } from '../db'; import { Product } from '../types';

export class ProductService { static async getById(id: number): Promise<Product | null> { const { rows } = await query('SELECT * FROM products WHERE id = $1', [id]); return rows[0] || null; }

static async create(data: Partial<Product>): Promise<Product> { const { rows } = await query( INSERT INTO products (name, description, price, stock) VALUES ($1, $2, $3, $4) RETURNING *, [data.name, data.description, data.price, data.stock] ); return rows[0]; }

static async list(limit: number, cursor?: string): Promise<{ items: Product[]; nextCursor?: string }> { let queryText = 'SELECT * FROM products ORDER BY id ASC LIMIT $1'; const params: any[] = [limit + 1]; // fetch one extra to know if there is a next page if (cursor) { const decoded = Buffer.from(cursor, 'base64').toString('utf8'); const lastId = JSON.parse(decoded).id; queryText = 'SELECT * FROM products WHERE id > $2 ORDER BY id ASC LIMIT $1'; params.push(lastId); } const { rows } = await query(queryText, params); const hasNext = rows.length > limit; const items = hasNext ? rows.slice(0, -1) : rows; const nextCursor = hasNext ? Buffer.from(JSON.stringify({ id: items[items.length - 1].id })).toString('base64') : undefined; return { items, nextCursor }; } }

5. Controller (src/controllers/product.controller.ts)

typescript import { Request, Response } from 'express'; import { ProductService } from '../services/product.service';

export class ProductController { static async getProduct(req: Request, res: Response) { const product = await ProductService.getById(parseInt(req.params.id, 10)); if (!product) return res.sendStatus(404); res.json(product); }

static async createProduct(req: Request, res: Response) { const product = await ProductService.create(req.body); res.status(201).json(product); }

static async listProducts(req: Request, res: Response) { const limit = Math.min(parseInt(req.query.limit as string) || 20, 100); const cursor = req.query.cursor as string | undefined; const { items, nextCursor } = await ProductService.list(limit, cursor); res.json({ items, nextCursor }); } }

6. Routes (src/routes/product.routes.ts)

typescript import { Router } from 'express'; import { ProductController } from '../controllers/product.controller'; import { authenticate } from '../middlewares/auth.middleware'; import { validate } from '../middlewares/validate.middleware'; import { body, param, query } from 'express-validator';

const router = Router();

router.get( '/:id', [param('id').isInt()], validate, ProductController.getProduct );

router.post( '/', authenticate, [ body('name').isString().notEmpty(), body('price').isFloat({ gt: 0 }), body('stock').isInt({ min: 0 }) ], validate, ProductController.createProduct );

router.get( '/', [ query('limit').optional().isInt({ min: 1, max: 100 }), query('cursor').optional().isString() ], validate, ProductController.listProducts );

export default router;

7. Application Bootstrap (src/app.ts)

typescript import express from 'express'; import helmet from 'helmet'; import morgan from 'morgan'; import productRoutes from './routes/product.routes';

const app = express(); app.use(helmet()); app.use(express.json()); app.use(morgan('combined'));

app.use('/api/v1/products', productRoutes);

app.use((_, res) => res.sendStatus(404));

const PORT = process.env.PORT || 3000; app.listen(PORT, () => console.log(🚀 API listening on port ${PORT}));

Deploying with Docker

dockerfile

Dockerfile

FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build

FROM node:20-alpine WORKDIR /app COPY --from=builder /app/dist ./dist COPY package*.json ./ RUN npm ci --only=production EXPOSE 3000 CMD ["node", "dist/app.js"]

Deploy the container behind an NGINX reverse proxy that supplies TLS termination and rate‑limiting using the ngx_http_limit_req_module.

---

Frequently Asked Questions

Q1: Should I use query parameters for filtering or create separate endpoints?

A: Keep the base resource URL stable and express filters with query parameters (e.g., GET /api/v1/products?category=books&minPrice=10). Separate endpoints are reserved for truly distinct concepts.

Q2: When is it appropriate to use GraphQL instead of REST?

A: GraphQL shines when clients need flexible field selection or when aggregating data from multiple services in a single round‑trip. For simple CRUD‑centric services with clear resource boundaries, REST remains easier to cache, monitor, and version.

Q3: How can I handle backward‑compatible changes without version bumps?

A: Additive changes such as new optional fields or additional endpoints are safe. Deprecate fields gradually by returning a Warning header and removing them only after a major version increment.

Q4: What pagination strategy works best for mobile clients?

A: Cursor‑based pagination minimizes skipped records and works well with infinite‑scroll UI patterns. It avoids the “page‑X‑of‑Y” problem where dataset mutations cause duplicate or missing entries.

---

Bringing It All Together

Designing a production‑ready RESTful API is more than writing endpoint functions; it demands a disciplined approach to resource modeling, HTTP semantics, security, and scalability. By applying the best practices outlined above-consistent URIs, proper status codes, versioning, cursor pagination, and layered architecture-you can deliver APIs that are easy to consume, maintain, and evolve.

The real‑world product catalog example illustrates how these principles translate into concrete code: Express routers handle validation, JWT middleware secures routes, a service layer isolates business rules, and PostgreSQL provides reliable persistence. Containerizing the service with Docker and placing it behind an NGINX gateway completes a deployment‑ready solution.

Adopt these patterns early, and your team will spend less time firefighting broken contracts and more time innovating on new features.

---