API Documentation

Introduction

Welcome to the API documentation for our platform. This API allows you to interact with our core services, manage users, products, and orders.

Base URL: https://api.example.com/v1

All requests should be made over HTTPS. The API uses JSON for request and response bodies.

Authentication

All API requests must be authenticated. We use API keys for authentication. Your API key should be included in the Authorization header as a Bearer token.

GET /auth/api-key

Request a new API key. This is a one-time operation.

Response Example (200 OK)

{
    "apiKey": "YOUR_GENERATED_API_KEY_HERE",
    "expiresAt": "2024-12-31T23:59:59Z"
}

Example Header:

Authorization: Bearer YOUR_GENERATED_API_KEY_HERE

Users

Manage user accounts and profiles.

GET /users

Retrieve a list of all users.

Query Parameters

Name Type Description Required
limit integer Maximum number of users to return. No
offset integer Number of users to skip. No

Response Example (200 OK)

[
    {
        "id": "user_abc123",
        "username": "johndoe",
        "email": "john.doe@example.com",
        "createdAt": "2023-01-15T10:30:00Z"
    },
    {
        "id": "user_def456",
        "username": "janedoe",
        "email": "jane.doe@example.com",
        "createdAt": "2023-01-16T11:00:00Z"
    }
]
GET /users/{userId}

Retrieve details for a specific user.

Path Parameters

Name Type Description Required
userId string The unique identifier for the user. Yes

Response Example (200 OK)

{
    "id": "user_abc123",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "isActive": true,
    "createdAt": "2023-01-15T10:30:00Z",
    "updatedAt": "2023-05-20T14:00:00Z"
}

Response Example (404 Not Found)

{
    "error": "User not found",
    "message": "The requested user ID could not be found."
}
POST /users

Create a new user account.

Request Body

{
    "username": "newuser",
    "email": "new.user@example.com",
    "password": "securepassword123",
    "firstName": "New",
    "lastName": "User"
}

Response Example (201 Created)

{
    "id": "user_ghi789",
    "username": "newuser",
    "email": "new.user@example.com",
    "createdAt": "2024-01-10T09:00:00Z"
}

Response Example (400 Bad Request)

{
    "error": "Invalid input",
    "message": "Username or email is already taken."
}

Products

Manage product listings.

GET /products

Retrieve a list of all available products.

Query Parameters

Name Type Description Required
category string Filter products by category. No
search string Search products by name or description. No

Response Example (200 OK)

[
    {
        "id": "prod_xyz789",
        "name": "Wireless Mouse",
        "price": 25.99,
        "currency": "USD",
        "category": "Electronics",
        "inStock": true
    },
    {
        "id": "prod_uvw456",
        "name": "Mechanical Keyboard",
        "price": 79.50,
        "currency": "USD",
        "category": "Electronics",
        "inStock": false
    }
]

Orders

Manage customer orders.

GET /orders

Retrieve a list of all orders.

Query Parameters

Name Type Description Required
userId string Filter orders by user ID. No
status string Filter orders by status (e.g., 'pending', 'shipped', 'delivered'). No

Response Example (200 OK)

[
    {
        "id": "order_jkl012",
        "userId": "user_abc123",
        "orderDate": "2024-01-10T12:00:00Z",
        "totalAmount": 105.49,
        "currency": "USD",
        "status": "shipped"
    },
    {
        "id": "order_mno345",
        "userId": "user_def456",
        "orderDate": "2024-01-11T15:30:00Z",
        "totalAmount": 25.99,
        "currency": "USD",
        "status": "delivered"
    }
]
POST /orders

Create a new order.

Request Body

{
    "userId": "user_abc123",
    "items": [
        {"productId": "prod_xyz789", "quantity": 2},
        {"productId": "prod_uvw456", "quantity": 1}
    ],
    "shippingAddress": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zipCode": "90210",
        "country": "USA"
    }
}

Response Example (201 Created)

{
    "id": "order_pqr678",
    "userId": "user_abc123",
    "orderDate": "2024-01-12T10:00:00Z",
    "totalAmount": 131.48,
    "currency": "USD",
    "status": "pending",
    "items": [
        {"productId": "prod_xyz789", "quantity": 2},
        {"productId": "prod_uvw456", "quantity": 1}
    ]
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses are returned in JSON format, including an error code and a human-readable message.

Common Error Codes:

Status Code Error Code Description
400 Bad Request invalid_input The request was malformed or contained invalid data.
401 Unauthorized unauthenticated Authentication credentials were missing or invalid.
403 Forbidden permission_denied The authenticated user does not have permission to perform the action.
404 Not Found not_found The requested resource could not be found.
405 Method Not Allowed method_not_allowed The HTTP method used is not supported for this resource.
500 Internal Server Error server_error An unexpected error occurred on the server.

Example Error Response (400):

{
    "error": "invalid_input",
    "message": "Email format is invalid."
}