REST API Endpoints

Overview

The REST API provides programmatic access to all platform resources. All endpoints follow RESTful conventions, accept JSON request bodies, and return JSON responses. Authentication is required for all endpoints unless otherwise noted.

Base URL

All API requests should be made to the following base URL:

https://api.example.com/v1

All endpoints described in this document are relative to this base URL. For example, the Users list endpoint is accessed at:

GET https://api.example.com/v1/users

Authentication

All API requests must include a valid authentication token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.example.com/v1/users

See the Authentication Overview for details on obtaining and managing API tokens.

Users Endpoints

The Users API allows you to create, read, update, and delete user accounts.

List All Users

Retrieve a paginated list of all users in the system.

GET /users

Query Parameters

Example Request

curl -X GET "https://api.example.com/v1/users?page=1&limit=10&sort=name&order=asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "role": "admin",
      "created_at": "2025-01-15T08:30:00Z",
      "updated_at": "2025-06-20T14:45:00Z"
    },
    {
      "id": 2,
      "name": "Bob Smith",
      "email": "bob@example.com",
      "role": "editor",
      "created_at": "2025-02-10T11:00:00Z",
      "updated_at": "2025-05-18T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_items": 47,
    "total_pages": 5
  }
}

Get a Specific User

Retrieve a single user by their unique identifier.

GET /users/{id}

Path Parameters

Example Request

curl -X GET "https://api.example.com/v1/users/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "data": {
    "id": 1,
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "admin",
    "avatar_url": "https://cdn.example.com/avatars/alice.jpg",
    "created_at": "2025-01-15T08:30:00Z",
    "updated_at": "2025-06-20T14:45:00Z",
    "last_login_at": "2025-07-01T09:15:00Z",
    "preferences": {
      "theme": "dark",
      "language": "en",
      "notifications": true
    }
  }
}

Create a User

Create a new user account.

POST /users

Request Body

Example Request

curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carol Davis",
    "email": "carol@example.com",
    "role": "editor",
    "password": "SecurePass123"
  }'

Example Response

{
  "data": {
    "id": 48,
    "name": "Carol Davis",
    "email": "carol@example.com",
    "role": "editor",
    "created_at": "2025-07-15T10:30:00Z",
    "updated_at": "2025-07-15T10:30:00Z"
  },
  "message": "User created successfully"
}

Products Endpoints

The Products API provides access to the product catalog.

List All Products

Retrieve a paginated list of all products.

GET /products

Query Parameters

Example Request

curl -X GET "https://api.example.com/v1/products?category=electronics&in_stock=true&limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": 101,
      "name": "Wireless Keyboard",
      "description": "Ergonomic wireless keyboard with backlit keys",
      "category": "electronics",
      "price": 79.99,
      "currency": "USD",
      "in_stock": true,
      "stock_quantity": 142,
      "created_at": "2025-03-01T12:00:00Z"
    },
    {
      "id": 102,
      "name": "USB-C Hub",
      "description": "7-port USB-C hub with HDMI and ethernet",
      "category": "electronics",
      "price": 49.99,
      "currency": "USD",
      "in_stock": true,
      "stock_quantity": 85,
      "created_at": "2025-03-15T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total_items": 23,
    "total_pages": 5
  }
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include a JSON body with additional details.

HTTP Status Codes

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      },
      {
        "field": "password",
        "message": "Must be at least 8 characters"
      }
    ]
  }
}

Error Codes

Rate Limiting

All API endpoints are rate-limited to ensure fair usage. The current limits are:

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1720000000