REST API Design Best Practices: Building Robust APIs

// Bad
GET /getUsers
POST /createUser
DELETE /deleteUser

// Good
GET /users
POST /users
DELETE /users/:id

GET /users          // Good
GET /user           // Bad

GET /authors/1/posts     // Get posts by author
GET /posts/1/comments    // Get comments on post

GET    /users        // Retrieve users
POST   /users        // Create new user
PUT    /users/1      // Update user (full)
PATCH  /users/1      // Update user (partial)
DELETE /users/1      // Delete user

// Request
POST /users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

// Response
{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2025-01-15T10:00:00Z"
}

200 OK              // Success
201 Created         // Resource created
204 No Content      // Successful deletion
400 Bad Request     // Invalid input
401 Unauthorized    // Not authenticated
403 Forbidden       // Authenticated but not authorized
404 Not Found       // Resource doesn't exist
500 Server Error    // Server error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}

GET /users?page=1&limit=20

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

/v1/users
/v2/users

GET /users?status=active&role=admin
GET /users?sort=-createdAt,name
GET /users?q=john