API Design

Resource Naming

• Use nouns for resources, not verbs
• Use plural nouns for collections
• Avoid deep nesting of resources
• Use lowercase, hyphens, and short names
• Be consistent across all endpoints

Good: /api/users/123/orders

Avoid: /api/getUserOrders?user_id=123

Status Codes

• Use standard HTTP status codes appropriately
• 200s for success (200 OK, 201 Created, 204 No Content)
• 400s for client errors (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 500s for server errors (500 Internal Server Error, 503 Service Unavailable)

Error Handling

• Return meaningful error messages
• Include error codes, messages, and details
• Avoid exposing sensitive information in errors
• Maintain consistency in error response format

{
  "error": {
    "code": "validation_failed",
    "message": "The request parameters are invalid.",
    "details": [
      { "field": "email", "message": "Must be a valid email address" },
      { "field": "age", "message": "Must be a positive integer" }
    ]
  }
}

Pagination

• Limit the number of items in response
• Provide consistent pagination parameters
• Include total count, links to next/previous pages
• Consider cursor-based pagination for large datasets

{
  "data": [...],
  "pagination": {
    "total_items": 1287,
    "total_pages": 129,
    "current_page": 3,
    "per_page": 10,
    "links": {
      "first": "/api/items?page=1&per_page=10",
      "prev": "/api/items?page=2&per_page=10",
      "next": "/api/items?page=4&per_page=10",
      "last": "/api/items?page=129&per_page=10"
    }
  }
}