API Design Principles

RESTful API design patterns and conventions used throughout the platform

Our API follows REST principles and industry best practices for consistency and ease of use.

Base URL

All API requests should be made to:

https://api.example.com/v1

HTTP Methods

We use standard HTTP methods:

Request Format

Headers

Content-Type: application/json
Authorization: Bearer {access_token}
X-Request-ID: {unique-request-id}

Request Body

{
  "name": "Example Resource",
  "description": "This is an example",
  "metadata": {
    "key": "value"
  }
}

Response Format

Success Response (200 OK)

{
  "data": {
    "id": "123",
    "name": "Example Resource",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Error Response (400 Bad Request)

{
  "error": {
    "code": "validation_error",
    "message": "Invalid input provided",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Status Codes

Common status codes you’ll encounter:

• 200 OK - Successful request
• 201 Created - Resource created successfully
• 204 No Content - Successful deletion
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource doesn’t exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Pagination

List endpoints support pagination:

GET /api/v1/resources?page=2&per_page=50

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 250,
    "total_pages": 5
  }
}

Filtering and Sorting

Filtering

GET /api/v1/resources?filter[status]=active&filter[type]=premium

Sorting

GET /api/v1/resources?sort=-created_at,name

• Prefix with - for descending order
• Multiple sort fields separated by commas

Versioning

API versioning is done via URL path:

• /v1/ - Current stable version
• /v2/ - Next major version (when available)

Rate Limiting

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1609459200

Best Practices

1. Always include proper error handling
2. Use request IDs for debugging
3. Implement exponential backoff for retries
4. Cache responses when appropriate
5. Use compression for large payloads
6. Monitor rate limits proactively