API Reference

Introduction

Welcome to the API Reference for our platform. This document details all available API endpoints, their request and response formats, and usage guidelines. Use this API to programmatically interact with user, product, and order data.

All API requests should be made over HTTPS. The base URL for all API endpoints is: https://api.example.com/v1

Authentication

Authentication is performed by passing an API key in the Authorization header of your requests.

Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key. You can obtain an API key from your developer dashboard.

Users API

[
    {
        "id": "usr_123abc",
        "name": "Alice Wonderland",
        "email": "alice@example.com",
        "status": "active",
        "created_at": "2023-10-27T10:00:00Z"
    },
    {
        "id": "usr_456def",
        "name": "Bob The Builder",
        "email": "bob@example.com",
        "status": "active",
        "created_at": "2023-10-27T10:05:00Z"
    }
]

{
    "error": "Unauthorized",
    "message": "Invalid API key."
}

{
    "name": "Charlie Chaplin",
    "email": "charlie@example.com",
    "status": "active"
}

{
    "id": "usr_789ghi",
    "name": "Charlie Chaplin",
    "email": "charlie@example.com",
    "status": "active",
    "created_at": "2023-10-27T11:00:00Z"
}

{
    "error": "Bad Request",
    "message": "Email is already in use."
}

{
    "id": "usr_123abc",
    "name": "Alice Wonderland",
    "email": "alice@example.com",
    "status": "active",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:30:00Z"
}

{
    "error": "Not Found",
    "message": "User with ID 'usr_nonexistent' not found."
}

{
    "name": "Alice Smith",
    "status": "inactive"
}

{
    "id": "usr_123abc",
    "name": "Alice Smith",
    "email": "alice@example.com",
    "status": "inactive",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T11:30:00Z"
}

{
    "error": "Not Found",
    "message": "User with ID 'usr_nonexistent' not found."
}

{
    "error": "Not Found",
    "message": "User with ID 'usr_nonexistent' not found."
}

Products API

[
    {
        "id": "prod_abc123",
        "name": "Wireless Mouse",
        "category": "Electronics",
        "price": 25.99,
        "in_stock": true
    },
    {
        "id": "prod_def456",
        "name": "Mechanical Keyboard",
        "category": "Electronics",
        "price": 79.50,
        "in_stock": false
    }
]

{
    "name": "Ergonomic Chair",
    "category": "Furniture",
    "price": 199.99,
    "in_stock": true,
    "description": "Comfortable ergonomic chair for long working hours."
}

{
    "id": "prod_ghi789",
    "name": "Ergonomic Chair",
    "category": "Furniture",
    "price": 199.99,
    "in_stock": true,
    "description": "Comfortable ergonomic chair for long working hours.",
    "created_at": "2023-10-27T12:00:00Z"
}

{
    "id": "prod_abc123",
    "name": "Wireless Mouse",
    "category": "Electronics",
    "price": 25.99,
    "in_stock": true,
    "description": "A high-precision wireless mouse with ergonomic design.",
    "created_at": "2023-10-26T09:00:00Z",
    "updated_at": "2023-10-27T09:15:00Z"
}

{
    "error": "Not Found",
    "message": "Product with ID 'prod_nonexistent' not found."
}

{
    "price": 27.50,
    "in_stock": false
}

{
    "id": "prod_abc123",
    "name": "Wireless Mouse",
    "category": "Electronics",
    "price": 27.50,
    "in_stock": false,
    "description": "A high-precision wireless mouse with ergonomic design.",
    "created_at": "2023-10-26T09:00:00Z",
    "updated_at": "2023-10-27T12:30:00Z"
}

{
    "error": "Not Found",
    "message": "Product with ID 'prod_nonexistent' not found."
}

{
    "error": "Not Found",
    "message": "Product with ID 'prod_nonexistent' not found."
}

Orders API

[
    {
        "id": "ord_xyz789",
        "user_id": "usr_123abc",
        "total_amount": 105.49,
        "status": "shipped",
        "created_at": "2023-10-27T13:00:00Z"
    },
    {
        "id": "ord_uvw456",
        "user_id": "usr_456def",
        "total_amount": 50.00,
        "status": "pending",
        "created_at": "2023-10-27T13:05:00Z"
    }
]

{
    "user_id": "usr_123abc",
    "items": [
        {
            "product_id": "prod_abc123",
            "quantity": 2
        },
        {
            "product_id": "prod_ghi789",
            "quantity": 1
        }
    ]
}

{
    "id": "ord_rst123",
    "user_id": "usr_123abc",
    "total_amount": 130.98,
    "status": "pending",
    "created_at": "2023-10-27T14:00:00Z",
    "items": [
        {
            "product_id": "prod_abc123",
            "quantity": 2,
            "price_at_order": 27.50
        },
        {
            "product_id": "prod_ghi789",
            "quantity": 1,
            "price_at_order": 75.98
        }
    ]
}

{
    "error": "Bad Request",
    "message": "One or more items are invalid or out of stock."
}

{
    "id": "ord_xyz789",
    "user_id": "usr_123abc",
    "total_amount": 105.49,
    "status": "shipped",
    "shipping_address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip_code": "90210"
    },
    "created_at": "2023-10-27T13:00:00Z",
    "updated_at": "2023-10-27T15:00:00Z",
    "items": [
        {
            "product_id": "prod_def456",
            "quantity": 1,
            "price_at_order": 79.50
        },
        {
            "product_id": "prod_abc123",
            "quantity": 1,
            "price_at_order": 25.99
        }
    ]
}

{
    "error": "Not Found",
    "message": "Order with ID 'ord_nonexistent' not found."
}