RESTful API Design Principlesfor Modern Applications

HTTP Methods and Their Usage

RESTful URL Examples

# Good URL Design
GET    /api/v1/users                    # Get all users
GET    /api/v1/users/123               # Get user with ID 123
POST   /api/v1/users                   # Create a new user
PUT    /api/v1/users/123               # Update user 123
DELETE /api/v1/users/123               # Delete user 123

# Nested Resources
GET    /api/v1/users/123/posts         # Get posts by user 123
POST   /api/v1/users/123/posts         # Create post for user 123
GET    /api/v1/users/123/posts/456     # Get specific post

# Query Parameters for Filtering
GET    /api/v1/users?role=admin&active=true
GET    /api/v1/posts?author=123&category=tech&limit=10

# Avoid These Patterns
GET    /api/v1/getUsers                # Don't use verbs in URLs
POST   /api/v1/users/create            # Method already indicates action
GET    /api/v1/user                    # Use plural nouns
                

Versioning Approaches

# 1. URL Path Versioning (Recommended)
GET /api/v1/users
GET /api/v2/users

# 2. Query Parameter Versioning
GET /api/users?version=1
GET /api/users?v=2

# 3. Header Versioning
GET /api/users
Headers: Accept: application/vnd.api+json;version=1

# 4. Content Type Versioning
GET /api/users
Headers: Accept: application/vnd.myapi.v1+json

# Version Compatibility Example
{
  "version": "2.1.0",
  "deprecations": [
    {
      "field": "user.email_verified",
      "replacement": "user.email_status",
      "removal_date": "2025-12-01"
    }
  ],
  "data": {
    "users": [...]
  }
}
                

Pagination and Filtering Examples

# Offset-based Pagination
GET /api/v1/users?limit=20&offset=40

# Cursor-based Pagination (Recommended for large datasets)
GET /api/v1/users?limit=20&cursor=eyJpZCI6MTIzfQ

# Response with Pagination Metadata
{
  "data": [...],
  "pagination": {
    "current_page": 3,
    "per_page": 20,
    "total_pages": 15,
    "total_count": 300,
    "next_cursor": "eyJpZCI6MTQzfQ",
    "has_more": true
  },
  "links": {
    "self": "/api/v1/users?limit=20&cursor=current",
    "next": "/api/v1/users?limit=20&cursor=eyJpZCI6MTQzfQ",
    "prev": "/api/v1/users?limit=20&cursor=eyJpZCI6MTAzfQ"
  }
}

# Advanced Filtering
GET /api/v1/users?filter[role]=admin&filter[status]=active&sort=-created_at,name
                

API Testing Strategy

# Example Test Cases

describe('Users API', () => {
  describe('GET /api/v1/users', () => {
    it('should return paginated users', async () => {
      const response = await request(app)
        .get('/api/v1/users?limit=10')
        .expect(200);
      
      expect(response.body).toHaveProperty('data');
      expect(response.body).toHaveProperty('pagination');
      expect(response.body.data).toHaveLength(10);
    });

    it('should filter users by role', async () => {
      const response = await request(app)
        .get('/api/v1/users?filter[role]=admin')
        .expect(200);
      
      response.body.data.forEach(user => {
        expect(user.role).toBe('admin');
      });
    });
  });

  describe('POST /api/v1/users', () => {
    it('should create a new user', async () => {
      const userData = {
        name: 'John Doe',
        email: 'john@example.com',
        role: 'user'
      };

      const response = await request(app)
        .post('/api/v1/users')
        .send(userData)
        .expect(201);
      
      expect(response.body.data).toMatchObject(userData);
    });

    it('should validate required fields', async () => {
      const response = await request(app)
        .post('/api/v1/users')
        .send({})
        .expect(422);
      
      expect(response.body.errors).toContain('name is required');
    });
  });
});