RESTful API Design: Best Practices for Modern Applications

Why API Design Matters

Your API is the contract between your services and consumers. Poor design leads to confusion, bugs, and frustrated developers. Great design creates delightful developer experiences and reduces support burden.

Core Principles

1. Use Nouns, Not Verbs

❌ Bad:
GET  /getUsers
POST /createUser
POST /updateUser/123
POST /deleteUser/123

✅ Good:
GET    /users          # List users
POST   /users          # Create user
GET    /users/123      # Get specific user
PUT    /users/123      # Update user
DELETE /users/123      # Delete user

2. Consistent Resource Naming

• Use plural nouns: /users, not /user
• Use kebab-case for URLs: /blog-posts
• Keep nesting shallow: /users/123/posts is okay, deeper gets unwieldy

3. Proper HTTP Methods

• GET - Retrieve resources (safe, idempotent, cacheable)
• POST - Create resources
• PUT - Replace entire resource
• PATCH - Partial update
• DELETE - Remove resource

Response Structure

Success Responses

// List endpoint
GET /users
{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

// Single resource
GET /users/123
{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      },
      {
        "field": "age",
        "message": "Must be 18 or older"
      }
    ]
  }
}

HTTP Status Codes

Success Codes

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

Client Error Codes

• 400 Bad Request - Invalid input
• 401 Unauthorized - Missing/invalid authentication
• 403 Forbidden - Authenticated but not authorized
• 404 Not Found - Resource doesn't exist
• 422 Unprocessable Entity - Validation failed
• 429 Too Many Requests - Rate limit exceeded

Server Error Codes

• 500 Internal Server Error - Something went wrong
• 503 Service Unavailable - Temporary outage

Pagination

Offset-Based (Simple)

GET /users?page=2&per_page=20

Response:
{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 20,
    "total": 500,
    "total_pages": 25
  }
}

Cursor-Based (Better for Large Datasets)

GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

Response:
{
  "data": [...],
  "cursors": {
    "next": "eyJpZCI6MTQzfQ",
    "prev": "eyJpZCI6MTAzfQ"
  }
}

Filtering and Sorting

// Filtering
GET /users?role=admin&status=active

// Sorting
GET /users?sort=-created_at,name  // Descending date, then name

// Combining
GET /users?role=admin&sort=-created_at&page=1&per_page=20

Versioning Strategies

URL Path (Recommended)

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

Header-Based

GET /api/users
Accept: application/vnd.myapi.v2+json

Security

Authentication

// JWT Bearer Token
Authorization: Bearer eyJhbGc...

// API Key
X-API-Key: your-api-key-here

Rate Limiting

// Response headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 985
X-RateLimit-Reset: 1640995200

// When exceeded
429 Too Many Requests
Retry-After: 3600

Documentation

Use OpenAPI (Swagger) for interactive documentation:

openapi: 3.0.0
info:
  title: Studio X API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success

Best Practices Checklist

1. ✅ Use consistent naming conventions
2. ✅ Implement proper error handling
3. ✅ Add pagination to list endpoints
4. ✅ Version your API from day one
5. ✅ Implement authentication and authorization
6. ✅ Add rate limiting
7. ✅ Return appropriate status codes
8. ✅ Include metadata in responses
9. ✅ Support filtering and sorting
10. ✅ Provide comprehensive documentation
11. ✅ Use HTTPS everywhere
12. ✅ Implement logging and monitoring

Conclusion

Great API design is about consistency, clarity, and developer experience. Follow these patterns to create APIs that are intuitive, maintainable, and scalable.

At Studio X Consulting, we design and build production APIs for enterprise clients. Need help designing your API strategy? Let's chat about how we can help.

Learn more at www.studioxconsulting.com. Contact Studio X Consulting to discuss legacy modernization, AI-assisted development, and delivery.