API Design Best Practices

Well-designed APIs are the backbone of modern applications. This guide covers essential principles for creating APIs that are intuitive, maintainable, and scalable.

RESTful Principles

Resource-Based URLs

Use nouns, not verbs:

✅ GET /users/123
❌ GET /getUser/123

✅ POST /users
❌ POST /createUser

HTTP Methods

Use appropriate HTTP verbs:

• GET - Retrieve resources
• POST - Create new resources
• PUT - Update entire resources
• PATCH - Partial updates
• DELETE - Remove resources

Status Codes

Return meaningful HTTP status codes:

200 OK - Successful GET, PUT, PATCH
201 Created - Successful POST
204 No Content - Successful DELETE
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required
404 Not Found - Resource doesn't exist
500 Internal Server Error - Server error

Response Design

Consistent Structure

Standardize response formats:

{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "timestamp": "2024-03-01T10:00:00Z",
    "version": "1.0"
  }
}

Pagination

Implement consistent pagination:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "hasNext": true,
    "hasPrev": false
  }
}

Error Handling

Structured Error Responses

Provide detailed error information:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning Strategies

URL Versioning

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

Header Versioning

Accept: application/vnd.api+json;version=1

Security Considerations

Authentication

Implement proper authentication:

// JWT token validation middleware
const authenticateToken = (req, res, next) => {
  const token = req.headers['authorization']?.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ error: 'Access token required' });
  }
  
  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) return res.status(403).json({ error: 'Invalid token' });
    req.user = user;
    next();
  });
};

Rate Limiting

Protect against abuse:

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});

Documentation

OpenAPI Specification

Document your APIs comprehensively:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Great API design balances developer experience, performance, and maintainability. Focus on consistency, clear documentation, and following established conventions.