REST Fundamentals

REST (Representational State Transfer) is an architectural style for designing networked applications. A well-designed REST API is intuitive, consistent, and a pleasure to work with.

Resource Naming

Use Nouns, Not Verbs

Resources should be named using nouns that represent entities:

✓ GET /users
✓ GET /users/123/orders
✗ GET /getUsers
✗ POST /createOrder

Use Plural Nouns

Maintain consistency by always using plural nouns for collections:

GET /users        # Get all users
GET /users/123    # Get specific user
POST /users       # Create new user

Hierarchical Relationships

Express relationships through URL hierarchy:

GET /users/123/orders          # User's orders
GET /users/123/orders/456      # Specific order
GET /orders/456/items          # Order items

HTTP Methods

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

Status Codes

Success Codes

• 200 OK: Successful GET, PUT, PATCH
• 201 Created: Successful POST with resource creation
• 204 No Content: Successful DELETE

Client Error Codes

• 400 Bad Request: Invalid request syntax
• 401 Unauthorized: Authentication required
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn't exist
• 422 Unprocessable Entity: Validation errors

Server Error Codes

• 500 Internal Server Error: Generic server error
• 503 Service Unavailable: Server temporarily unavailable

Versioning Strategies

URL Path Versioning

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

Header Versioning

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

Pagination

GET /users?page=2&limit=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Error Response Format

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

Documentation

Use OpenAPI/Swagger to document your APIs. Include examples, authentication requirements, and rate limiting information.

Conclusion

A well-designed API is an investment that pays dividends in developer productivity and system maintainability. Follow these patterns consistently across your organization.