API Design Skill

Best practices for designing clear, consistent, and maintainable REST APIs.

Core Principles

1. •Consistency - Follow same patterns across all endpoints
2. •Predictability - Behavior matches expectations
3. •Simplicity - Easy to understand and use
4. •Versioning - Plan for changes over time
5. •Documentation - Clear, up-to-date docs

Resource Naming

Use Nouns, Not Verbs

Bad:  /getUsers, /createUser, /deleteUser
Good: GET /users, POST /users, DELETE /users/:id

Plural Resource Names

Bad:  /user/:id
Good: /users/:id

Nested Resources (max 2 levels)

/users/:userId/posts
/posts/:postId/comments

HTTP Methods

GET    /users          # List all users
GET    /users/:id      # Get specific user
POST   /users          # Create new user
PUT    /users/:id      # Replace entire user
PATCH  /users/:id      # Update partial user
DELETE /users/:id      # Delete user

Status Codes

Success (2xx)

• •200 OK - Successful GET, PUT, PATCH
• •201 Created - Successful POST
• •204 No Content - Successful DELETE

Client Errors (4xx)

• •400 Bad Request - Invalid input
• •401 Unauthorized - Not authenticated
• •403 Forbidden - Not allowed
• •404 Not Found - Resource doesn't exist
• •422 Unprocessable - Validation failed
• •429 Too Many Requests - Rate limited

Server Errors (5xx)

• •500 Internal Error - Server error
• •503 Service Unavailable - Overloaded

Request/Response Format

Success Response

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

List Response with Pagination

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

Error Response

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Email is required",
    "details": {
      "field": "email",
      "reason": "missing_field"
    }
  }
}

Query Parameters

Filtering

GET /users?role=admin&active=true

Sorting

GET /users?sort=name
GET /users?sort=-created_at  # descending

Pagination

GET /users?page=2&per_page=20

Field Selection

GET /users?fields=id,name,email

Versioning

URL Versioning (Recommended)

/api/v1/users
/api/v2/users

Authentication

Bearer Token

Authorization: Bearer <token>

Rate Limiting Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Best Practices Checklist

• • Use nouns for resources
• • Plural resource names
• • Proper HTTP methods
• • Appropriate status codes
• • Consistent JSON structure
• • Input validation
• • Error handling
• • Authentication
• • Rate limiting
• • Pagination for lists
• • API versioning
• • Documentation
• • HTTPS only

Remember

• •Consistency is key
• •Think from client perspective
• •Design for evolution
• •Document everything
• •Security first