API Design & Development - 2/3
From Design Principles to Production Implementation
You understand REST principles, resource-based URLs, HTTP methods, and status codes. You can design APIs that look professional on paper. But here’s the reality: beautifully designed APIs are worthless if they don’t handle real-world data properly, validate inputs securely, or provide meaningful error messages.
The implementation gap most developers fall into:
// Looks good in documentation
app.post("/api/v1/users", (req, res) => {
const user = createUser(req.body); // What could go wrong?
res.status(201).json(user);
});
// Reality with real users
app.post("/api/v1/users", (req, res) => {
const user = createUser({
name: "<script>alert('XSS')</script>", // Script injection
email: "definitely-not-an-email", // Invalid format
age: "twenty-five", // Wrong type
password: "", // Empty required field
role: "admin", // Privilege escalation
extraField: "this shouldn't be here", // Unknown fields
});
// Server crashes, database corrupted, security compromised
});
The brutal truth: Users will send malformed data, malicious payloads, missing fields, wrong types, and unexpected structures. Your API either handles this gracefully or becomes a security liability.
Professional APIs require robust implementation:
- Structured request/response formats that are consistent and predictable
- Comprehensive input validation that protects against malicious and malformed data
- Standardized error responses that help clients handle failures gracefully
- Complete API documentation that enables integration without guessing
- Thorough testing strategies that verify behavior under all conditions
This article bridges the gap between API design and bulletproof implementation. You’ll learn to build APIs that don’t just follow REST principles but actually work reliably with real-world data from untrusted sources.
Request/Response Formats: Structured Data Exchange
JSON: The Default Choice
JSON has become the standard for web APIs due to its simplicity, readability, and universal language support. But proper JSON handling requires more thought than most developers realize.
Request Format Standards
Consistent JSON structure for requests:
// ✅ Well-structured request format
app.post('/api/v1/users', (req, res) => {
const { name, email, profile, preferences } = req.body;
// Expected structure:
// {
// "name": "Alice Johnson",
// "email": "alice@example.com",
// "profile": {
// "bio": "Software developer",
// "avatar": "https://example.com/avatar.jpg"
// },
// "preferences": {
// "newsletter": true,
// "notifications": false
// }
// }
const newUser = await createUser({ name, email, profile, preferences });
res.status(201).json({ user: newUser });
});
Handle nested data appropriately:
// Complex resource with relationships
app.post("/api/v1/orders", async (req, res) => {
const {
customerId,
items, // Array of order items
shippingAddress, // Nested address object
paymentMethod, // Nested payment object
metadata, // Optional additional data
} = req.body;
// Expected structure:
// {
// "customerId": 123,
// "items": [
// { "productId": 456, "quantity": 2, "price": 29.99 },
// { "productId": 789, "quantity": 1, "price": 49.99 }
// ],
// "shippingAddress": {
// "street": "123 Main St",
// "city": "Springfield",
// "state": "IL",
// "zipCode": "62701"
// },
// "paymentMethod": {
// "type": "credit_card",
// "token": "tok_1234567890"
// },
// "metadata": {
// "source": "mobile_app",
// "campaignId": "summer_sale"
// }
// }
const order = await createOrder({
customerId,
items,
shippingAddress,
paymentMethod,
metadata,
});
res.status(201).json({ order });
});
Response Format Consistency
Standardize response structure across your API:
// Response format helper
const createResponse = (success, data, message, meta = {}) => {
const response = {
success,
message,
timestamp: new Date().toISOString(),
...meta,
};
if (data !== null) {
response.data = data;
}
return response;
};
// Consistent success responses
app.get("/api/v1/users", async (req, res) => {
const { page = 1, limit = 10 } = req.query;
const result = await getUsersPaginated(page, limit);
res.json(
createResponse(true, result.users, "Users retrieved successfully", {
pagination: {
page: parseInt(page),
limit: parseInt(limit),
total: result.total,
totalPages: Math.ceil(result.total / limit),
},
})
);
});
// Consistent error responses
app.get("/api/v1/users/:id", async (req, res) => {
try {
const user = await getUserById(req.params.id);
if (!user) {
return res
.status(404)
.json(createResponse(false, null, "User not found"));
}
res.json(createResponse(true, { user }, "User retrieved successfully"));
} catch (error) {
res.status(500).json(createResponse(false, null, "Internal server error"));
}
});
Content Negotiation
Support multiple formats when needed:
app.get("/api/v1/users/:id", async (req, res) => {
const user = await getUserById(req.params.id);
if (!user) {
return res.status(404).json({ error: "User not found" });
}
res.format({
"application/json": () => {
res.json({ user });
},
"application/xml": () => {
const xml = `
<user>
<id>${user.id}</id>
<name>${user.name}</name>
<email>${user.email}</email>
</user>
`;
res.set("Content-Type", "application/xml");
res.send(xml);
},
"text/csv": () => {
const csv = `id,name,email\n${user.id},${user.name},${user.email}`;
res.set("Content-Type", "text/csv");
res.set("Content-Disposition", 'attachment; filename="user.csv"');
res.send(csv);
},
default: () => {
res.status(406).json({ error: "Not Acceptable" });
},
});
});
Large Response Handling
Implement pagination and field selection:
app.get("/api/v1/users", async (req, res) => {
const {
page = 1,
limit = 10,
sort = "created_at",
order = "desc",
fields, // Comma-separated field list
search,
} = req.query;
// Build query options
const options = {
page: parseInt(page),
limit: Math.min(parseInt(limit), 100), // Cap at 100
sort,
order,
search,
};
// Field selection
const selectedFields = fields ? fields.split(",") : null;
const result = await getUsersPaginated(options);
// Apply field selection
let users = result.users;
if (selectedFields) {
users = users.map((user) => {
const selectedUser = {};
selectedFields.forEach((field) => {
if (user[field] !== undefined) {
selectedUser[field] = user[field];
}
});
return selectedUser;
});
}
res.json({
users,
pagination: {
page: options.page,
limit: options.limit,
total: result.total,
totalPages: Math.ceil(result.total / options.limit),
hasNext: options.page * options.limit < result.total,
hasPrev: options.page > 1,
},
});
});
Input Validation: Your Security Frontline
Why Validation Is Critical
Every input is a potential attack vector. Proper validation prevents:
- SQL injection: Malicious database queries
- XSS attacks: Script injection in responses
- NoSQL injection: Document database manipulation
- Buffer overflows: Memory corruption
- Business logic bypass: Invalid state changes
- Resource exhaustion: DoS through large payloads
Schema-Based Validation
Use validation libraries for robust input checking:
npm install joi # or yup, zod, express-validator
Joi validation example:
const Joi = require("joi");
// Define validation schemas
const createUserSchema = Joi.object({
name: Joi.string()
.min(2)
.max(50)
.pattern(/^[a-zA-Z\s]+$/) // Only letters and spaces
.required()
.messages({
"string.empty": "Name is required",
"string.min": "Name must be at least 2 characters",
"string.max": "Name cannot exceed 50 characters",
"string.pattern.base": "Name can only contain letters and spaces",
}),
email: Joi.string().email().required().messages({
"string.email": "Please provide a valid email address",
}),
age: Joi.number().integer().min(13).max(120).optional().messages({
"number.min": "Age must be at least 13",
"number.max": "Age cannot exceed 120",
}),
password: Joi.string()
.min(8)
.pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]/)
.required()
.messages({
"string.min": "Password must be at least 8 characters",
"string.pattern.base":
"Password must contain uppercase, lowercase, number, and special character",
}),
profile: Joi.object({
bio: Joi.string().max(500).optional(),
website: Joi.string().uri().optional(),
avatar: Joi.string().uri().optional(),
}).optional(),
preferences: Joi.object({
newsletter: Joi.boolean().default(false),
notifications: Joi.boolean().default(true),
theme: Joi.string().valid("light", "dark").default("light"),
}).optional(),
});
// Validation middleware
const validateCreateUser = (req, res, next) => {
const { error, value } = createUserSchema.validate(req.body, {
abortEarly: false, // Return all errors, not just the first
stripUnknown: true, // Remove unknown fields
});
if (error) {
const errors = error.details.map((detail) => ({
field: detail.path.join("."),
message: detail.message,
value: detail.context.value,
}));
return res.status(400).json({
success: false,
message: "Validation failed",
errors,
});
}
req.body = value; // Use validated and sanitized data
next();
};
// Apply validation to route
app.post("/api/v1/users", validateCreateUser, async (req, res) => {
try {
// req.body is now validated and sanitized
const newUser = await createUser(req.body);
res.status(201).json({
success: true,
message: "User created successfully",
data: { user: newUser },
});
} catch (error) {
res.status(500).json({
success: false,
message: "Failed to create user",
});
}
});
Custom Validation Logic
For complex business rules:
const validateOrderItems = (req, res, next) => {
const { items } = req.body;
if (!Array.isArray(items) || items.length === 0) {
return res.status(400).json({
error: "Order must contain at least one item",
});
}
// Validate each item
for (let i = 0; i < items.length; i++) {
const item = items[i];
// Check required fields
if (!item.productId || !item.quantity || !item.price) {
return res.status(400).json({
error: `Item ${
i + 1
} is missing required fields (productId, quantity, price)`,
});
}
// Business logic validation
if (item.quantity > 100) {
return res.status(400).json({
error: `Item ${i + 1} exceeds maximum quantity limit (100)`,
});
}
if (item.price < 0) {
return res.status(400).json({
error: `Item ${i + 1} has invalid price (must be positive)`,
});
}
}
// Check for duplicate products
const productIds = items.map((item) => item.productId);
const uniqueProductIds = new Set(productIds);
if (productIds.length !== uniqueProductIds.size) {
return res.status(400).json({
error: "Order contains duplicate products",
});
}
next();
};
app.post("/api/v1/orders", validateOrderItems, async (req, res) => {
// Order items are validated
const order = await createOrder(req.body);
res.status(201).json({ order });
});
Sanitization and Security
Clean and secure user input:
const sanitizeHtml = require("sanitize-html");
const validator = require("validator");
const sanitizeUserInput = (req, res, next) => {
if (req.body.name) {
// Remove HTML tags and dangerous characters
req.body.name = sanitizeHtml(req.body.name, {
allowedTags: [],
allowedAttributes: {},
}).trim();
}
if (req.body.email) {
// Normalize email
req.body.email = validator.normalizeEmail(req.body.email);
}
if (req.body.profile && req.body.profile.bio) {
// Allow basic formatting in bio but sanitize
req.body.profile.bio = sanitizeHtml(req.body.profile.bio, {
allowedTags: ["b", "i", "em", "strong", "p", "br"],
allowedAttributes: {},
});
}
if (req.body.profile && req.body.profile.website) {
// Validate and normalize URL
if (!validator.isURL(req.body.profile.website)) {
return res.status(400).json({
error: "Invalid website URL format",
});
}
}
next();
};
app.post(
"/api/v1/users",
sanitizeUserInput,
validateCreateUser,
async (req, res) => {
// Input is sanitized and validated
const newUser = await createUser(req.body);
res.status(201).json({ user: newUser });
}
);
Error Response Standardization
Consistent Error Format
Standardize error responses across your entire API:
// Error response builder
class APIError extends Error {
constructor(message, statusCode = 500, code = null, details = null) {
super(message);
this.statusCode = statusCode;
this.code = code;
this.details = details;
this.isOperational = true;
}
}
// Error formatter
const formatErrorResponse = (error, req) => {
const response = {
success: false,
error: {
message: error.message,
code: error.code || "INTERNAL_ERROR",
timestamp: new Date().toISOString(),
path: req.url,
method: req.method,
},
};
// Add details for validation errors
if (error.details) {
response.error.details = error.details;
}
// Add stack trace in development
if (process.env.NODE_ENV === "development") {
response.error.stack = error.stack;
}
// Add request ID for tracing
if (req.id) {
response.error.requestId = req.id;
}
return response;
};
// Global error handler
const errorHandler = (err, req, res, next) => {
let error = err;
// Handle different error types
if (err.name === "ValidationError") {
error = new APIError(
"Validation failed",
400,
"VALIDATION_ERROR",
Object.values(err.errors).map((e) => ({
field: e.path,
message: e.message,
}))
);
} else if (err.name === "CastError") {
error = new APIError("Invalid ID format", 400, "INVALID_ID");
} else if (err.code === 11000) {
// MongoDB duplicate key error
const field = Object.keys(err.keyValue)[0];
error = new APIError(`${field} already exists`, 409, "DUPLICATE_ENTRY", {
field,
value: err.keyValue[field],
});
} else if (!err.isOperational) {
// Programming errors shouldn't expose details
error = new APIError("Something went wrong", 500, "INTERNAL_ERROR");
}
const formattedError = formatErrorResponse(error, req);
res.status(error.statusCode).json(formattedError);
};
app.use(errorHandler);
Specific Error Types
Create specific error classes for common scenarios:
// Specific error types
class ValidationError extends APIError {
constructor(message, details) {
super(message, 400, "VALIDATION_ERROR", details);
}
}
class NotFoundError extends APIError {
constructor(resource) {
super(`${resource} not found`, 404, "NOT_FOUND");
}
}
class UnauthorizedError extends APIError {
constructor(message = "Unauthorized") {
super(message, 401, "UNAUTHORIZED");
}
}
class ForbiddenError extends APIError {
constructor(message = "Access forbidden") {
super(message, 403, "FORBIDDEN");
}
}
class ConflictError extends APIError {
constructor(message, details = null) {
super(message, 409, "CONFLICT", details);
}
}
class RateLimitError extends APIError {
constructor(message = "Rate limit exceeded") {
super(message, 429, "RATE_LIMIT_EXCEEDED");
}
}
// Usage in routes
app.get("/api/v1/users/:id", async (req, res, next) => {
try {
const user = await getUserById(req.params.id);
if (!user) {
throw new NotFoundError("User");
}
res.json({ user });
} catch (error) {
next(error);
}
});
app.post("/api/v1/users", async (req, res, next) => {
try {
const existingUser = await getUserByEmail(req.body.email);
if (existingUser) {
throw new ConflictError("User already exists", {
field: "email",
value: req.body.email,
});
}
const newUser = await createUser(req.body);
res.status(201).json({ user: newUser });
} catch (error) {
next(error);
}
});
Error Context and Debugging
Provide helpful error context:
const contextualErrorHandler = (err, req, res, next) => {
// Log full error details server-side
console.error("API Error:", {
message: err.message,
stack: err.stack,
url: req.url,
method: req.method,
body: req.body,
params: req.params,
query: req.query,
headers: req.headers,
user: req.user?.id || "anonymous",
timestamp: new Date().toISOString(),
});
// Send appropriate response to client
const response = {
success: false,
error: {
message: err.message,
code: err.code || "INTERNAL_ERROR",
timestamp: new Date().toISOString(),
},
};
// Add helpful context for client-side errors
if (err.statusCode < 500) {
response.error.help = {
documentation: `https://docs.myapi.com/errors/${err.code}`,
support: "support@myapi.com",
};
if (err.code === "VALIDATION_ERROR" && err.details) {
response.error.details = err.details;
response.error.help.example =
"Check the API documentation for correct request format";
}
if (err.code === "UNAUTHORIZED") {
response.error.help.example =
"Ensure you include a valid Authorization header";
}
}
res.status(err.statusCode || 500).json(response);
};
API Documentation with OpenAPI/Swagger
Introduction to OpenAPI
OpenAPI (formerly Swagger) is the industry standard for documenting REST APIs. It provides:
- Interactive documentation: Test API endpoints directly from docs
- Code generation: Generate client libraries for different languages
- Validation: Ensure requests/responses match specifications
- Mock servers: Create mock APIs for frontend development
Setting Up Swagger with Express
npm install swagger-ui-express swagger-jsdoc
Basic Swagger setup:
const swaggerUi = require("swagger-ui-express");
const swaggerJsdoc = require("swagger-jsdoc");
// Swagger configuration
const swaggerOptions = {
definition: {
openapi: "3.0.0",
info: {
title: "User Management API",
version: "1.0.0",
description: "A comprehensive API for managing users and their data",
contact: {
name: "API Support",
email: "support@myapi.com",
url: "https://myapi.com/support",
},
license: {
name: "MIT",
url: "https://opensource.org/licenses/MIT",
},
},
servers: [
{
url: "http://localhost:3000/api/v1",
description: "Development server",
},
{
url: "https://api.myapp.com/v1",
description: "Production server",
},
],
components: {
securitySchemes: {
bearerAuth: {
type: "http",
scheme: "bearer",
bearerFormat: "JWT",
},
},
schemas: {
User: {
type: "object",
required: ["name", "email"],
properties: {
id: {
type: "integer",
description: "Unique user identifier",
},
name: {
type: "string",
minLength: 2,
maxLength: 50,
description: "User full name",
},
email: {
type: "string",
format: "email",
description: "User email address",
},
profile: {
type: "object",
properties: {
bio: { type: "string", maxLength: 500 },
avatar: { type: "string", format: "uri" },
website: { type: "string", format: "uri" },
},
},
createdAt: {
type: "string",
format: "date-time",
description: "User creation timestamp",
},
},
},
Error: {
type: "object",
properties: {
success: { type: "boolean", example: false },
error: {
type: "object",
properties: {
message: { type: "string" },
code: { type: "string" },
timestamp: { type: "string", format: "date-time" },
},
},
},
},
},
},
},
apis: ["./routes/*.js"], // Path to files with API docs
};
const swaggerSpec = swaggerJsdoc(swaggerOptions);
// Serve Swagger UI
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
Documenting Endpoints
Use JSDoc comments to document routes:
/**
* @swagger
* /users:
* get:
* summary: Get all users
* tags: [Users]
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* minimum: 1
* default: 1
* description: Page number for pagination
* - in: query
* name: limit
* schema:
* type: integer
* minimum: 1
* maximum: 100
* default: 10
* description: Number of users per page
* - in: query
* name: search
* schema:
* type: string
* description: Search term for user names or emails
* responses:
* 200:
* description: Users retrieved successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* example: true
* data:
* type: object
* properties:
* users:
* type: array
* items:
* $ref: '#/components/schemas/User'
* pagination:
* type: object
* properties:
* page: { type: integer }
* limit: { type: integer }
* total: { type: integer }
* totalPages: { type: integer }
* 500:
* description: Internal server error
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
*/
app.get("/users", async (req, res) => {
// Implementation here
});
/**
* @swagger
* /users:
* post:
* summary: Create a new user
* tags: [Users]
* security:
* - bearerAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - name
* - email
* - password
* properties:
* name:
* type: string
* minLength: 2
* maxLength: 50
* example: "Alice Johnson"
* email:
* type: string
* format: email
* example: "alice@example.com"
* password:
* type: string
* minLength: 8
* example: "SecurePass123!"
* profile:
* type: object
* properties:
* bio:
* type: string
* maxLength: 500
* example: "Software developer and tech enthusiast"
* website:
* type: string
* format: uri
* example: "https://alicejohnson.dev"
* responses:
* 201:
* description: User created successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* example: true
* data:
* type: object
* properties:
* user:
* $ref: '#/components/schemas/User'
* 400:
* description: Validation error
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 409:
* description: User already exists
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
*/
app.post("/users", validateCreateUser, async (req, res) => {
// Implementation here
});
API Testing with Postman and Automated Tests
Postman Collections
Organize API tests in Postman collections:
{
"info": {
"name": "User Management API",
"description": "Complete test suite for user management endpoints",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/"
},
"variable": [
{
"key": "baseUrl",
"value": "http://localhost:3000/api/v1"
},
{
"key": "authToken",
"value": ""
}
],
"item": [
{
"name": "Authentication",
"item": [
{
"name": "Login",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\"email\": \"test@example.com\", \"password\": \"password123\"}"
},
"url": "{{baseUrl}}/auth/login"
},
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Login successful', function () {",
" pm.response.to.have.status(200);",
" const response = pm.response.json();",
" pm.expect(response.success).to.be.true;",
" pm.expect(response.data).to.have.property('token');",
" pm.collectionVariables.set('authToken', response.data.token);",
"});"
]
}
}
]
}
]
},
{
"name": "Users",
"item": [
{
"name": "Create User",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
},
{
"key": "Authorization",
"value": "Bearer {{authToken}}"
}
],
"body": {
"mode": "raw",
"raw": "{\"name\": \"Test User\", \"email\": \"{{$randomEmail}}\", \"password\": \"SecurePass123!\"}"
},
"url": "{{baseUrl}}/users"
},
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('User created successfully', function () {",
" pm.response.to.have.status(201);",
" const response = pm.response.json();",
" pm.expect(response.success).to.be.true;",
" pm.expect(response.data.user).to.have.property('id');",
" pm.collectionVariables.set('userId', response.data.user.id);",
"});"
]
}
}
]
},
{
"name": "Get User",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{authToken}}"
}
],
"url": "{{baseUrl}}/users/{{userId}}"
},
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('User retrieved successfully', function () {",
" pm.response.to.have.status(200);",
" const response = pm.response.json();",
" pm.expect(response.success).to.be.true;",
" pm.expect(response.data.user).to.have.property('id');",
" pm.expect(response.data.user.id).to.equal(pm.collectionVariables.get('userId'));",
"});"
]
}
}
]
}
]
}
]
}
Automated API Testing
Use testing frameworks for comprehensive API testing:
npm install --save-dev jest supertest
Integration test example:
// tests/users.test.js
const request = require("supertest");
const app = require("../server");
describe("Users API", () => {
let authToken;
let userId;
beforeAll(async () => {
// Login to get auth token
const loginResponse = await request(app).post("/api/v1/auth/login").send({
email: "test@example.com",
password: "password123",
});
authToken = loginResponse.body.data.token;
});
describe("POST /api/v1/users", () => {
it("should create a new user with valid data", async () => {
const userData = {
name: "Test User",
email: `test${Date.now()}@example.com`,
password: "SecurePass123!",
profile: {
bio: "Test user bio",
},
};
const response = await request(app)
.post("/api/v1/users")
.set("Authorization", `Bearer ${authToken}`)
.send(userData);
expect(response.status).toBe(201);
expect(response.body.success).toBe(true);
expect(response.body.data.user).toHaveProperty("id");
expect(response.body.data.user.name).toBe(userData.name);
expect(response.body.data.user.email).toBe(userData.email);
userId = response.body.data.user.id;
});
it("should reject user creation with invalid email", async () => {
const userData = {
name: "Test User",
email: "invalid-email",
password: "SecurePass123!",
};
const response = await request(app)
.post("/api/v1/users")
.set("Authorization", `Bearer ${authToken}`)
.send(userData);
expect(response.status).toBe(400);
expect(response.body.success).toBe(false);
expect(response.body.error.code).toBe("VALIDATION_ERROR");
});
it("should reject duplicate email addresses", async () => {
const userData = {
name: "Another User",
email: "test@example.com", // Existing email
password: "SecurePass123!",
};
const response = await request(app)
.post("/api/v1/users")
.set("Authorization", `Bearer ${authToken}`)
.send(userData);
expect(response.status).toBe(409);
expect(response.body.success).toBe(false);
expect(response.body.error.code).toBe("CONFLICT");
});
});
describe("GET /api/v1/users/:id", () => {
it("should retrieve user by ID", async () => {
const response = await request(app)
.get(`/api/v1/users/${userId}`)
.set("Authorization", `Bearer ${authToken}`);
expect(response.status).toBe(200);
expect(response.body.success).toBe(true);
expect(response.body.data.user.id).toBe(userId);
});
it("should return 404 for non-existent user", async () => {
const response = await request(app)
.get("/api/v1/users/99999")
.set("Authorization", `Bearer ${authToken}`);
expect(response.status).toBe(404);
expect(response.body.success).toBe(false);
expect(response.body.error.code).toBe("NOT_FOUND");
});
});
describe("GET /api/v1/users", () => {
it("should support pagination", async () => {
const response = await request(app)
.get("/api/v1/users?page=1&limit=5")
.set("Authorization", `Bearer ${authToken}`);
expect(response.status).toBe(200);
expect(response.body.success).toBe(true);
expect(response.body.data.users).toHaveLength(5);
expect(response.body.data.pagination).toHaveProperty("page", 1);
expect(response.body.data.pagination).toHaveProperty("limit", 5);
});
it("should support search functionality", async () => {
const response = await request(app)
.get("/api/v1/users?search=test")
.set("Authorization", `Bearer ${authToken}`);
expect(response.status).toBe(200);
expect(response.body.success).toBe(true);
response.body.data.users.forEach((user) => {
expect(
user.name.toLowerCase().includes("test") ||
user.email.toLowerCase().includes("test")
).toBe(true);
});
});
});
});
Key Takeaways
Professional API implementation requires attention to data formats, validation, error handling, documentation, and testing. These aren’t optional extras—they’re essential components that separate hobby projects from production-ready systems.
The implementation mindset you need:
- Trust nothing from clients: Every input must be validated and sanitized
- Consistency across all endpoints: Use standardized formats for requests, responses, and errors
- Documentation is not optional: APIs without docs are unusable by other developers
- Testing is your safety net: Comprehensive tests prevent regressions and catch edge cases
What distinguishes production-ready API implementation:
- Robust input validation that prevents security vulnerabilities
- Consistent error responses that help clients handle failures gracefully
- Complete API documentation that enables integration without guesswork
- Comprehensive testing that covers happy paths, edge cases, and error conditions
What’s Next
We’ve covered the implementation fundamentals that make well-designed APIs actually work in production. In the next article, we’ll complete the API design trilogy by diving into GraphQL, real-time APIs with WebSockets, rate limiting strategies, API gateways, and webhooks for event-driven architectures.
The foundation is solid—you understand both the design principles and implementation details of professional REST APIs. Next, we’ll explore advanced patterns and alternative approaches that handle complex requirements and scale to enterprise levels.
You’re building the comprehensive knowledge that separates API consumers from API architects. The complexity increases, but so does your ability to solve sophisticated integration challenges.