API Design Standards

Guidelines for designing RESTful APIs.

URL Structure

Resources

Use nouns, not verbs:

GET    /users          # List users
POST   /users          # Create user
GET    /users/:id      # Get user
PATCH  /users/:id      # Update user
DELETE /users/:id      # Delete user

Nested Resources

GET    /users/:id/posts     # Get user's posts
POST   /users/:id/posts     # Create post for user
GET    /posts/:id/comments  # Get post's comments

Query Parameters

GET /users?page=1&limit=20           # Pagination
GET /users?sort=created_at&order=desc # Sorting
GET /users?status=active             # Filtering
GET /users?search=john               # Search

HTTP Methods

Method	Purpose	Idempotent
GET	Retrieve data	Yes
POST	Create resource	No
PUT	Replace resource	Yes
PATCH	Update resource	Yes
DELETE	Remove resource	Yes

Status Codes

Success

• 200 OK - Successful GET, PATCH, DELETE
• 201 Created - Successful POST
• 204 No Content - Successful DELETE with no body

Client Errors

• 400 Bad Request - Invalid input
• 401 Unauthorized - Not authenticated
• 403 Forbidden - Not authorized
• 404 Not Found - Resource doesn't exist
• 409 Conflict - Resource conflict
• 422 Unprocessable Entity - Validation failed

Server Errors

• 500 Internal Server Error - Unexpected error
• 503 Service Unavailable - Temporarily unavailable

Request/Response Format

Request Body

POST /users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]"
}

Success Response

{
  "data": {
    "id": "usr_123",
    "name": "John Doe",
    "email": "[email protected]",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Response

{
  "data": [
    { "id": "usr_123", "name": "John" },
    { "id": "usr_456", "name": "Jane" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

Naming Conventions

URLs

• Use lowercase
• Use hyphens for multi-word: /user-profiles
• Use plural nouns: /users not /user

Fields

• Use camelCase: firstName, createdAt
• Use consistent naming across endpoints
• Use ISO 8601 for dates: 2024-01-15T10:30:00Z

Versioning

Include version in URL:

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

Pagination

Offset-based

GET /users?page=2&limit=20

Cursor-based (for large datasets)

GET /users?cursor=abc123&limit=20

Authentication

Use Bearer tokens:

Authorization: Bearer <token>

Rate Limiting

Include headers:

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

Best Practices

1. Be consistent - Same patterns everywhere
2. Use proper status codes - Not just 200 and 500
3. Validate input - Return helpful error messages
4. Document everything - Keep API docs up to date
5. Version from the start - Easier than adding later