API Reference

Authentication

User Login

POST /api/v1/auth/login

Authenticates a user and returns an access token.

Parameters

Name Type Required Description
email String Yes The user's email address.
password String Yes The user's password.

Responses

Status Code Description Content
200 OK Login successful. 
{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
}
401 Unauthorized Invalid credentials. 
{
    "error": "Invalid email or password"
}

Refresh Token

POST /api/v1/auth/refresh

Refreshes an expired access token using a valid refresh token.

Parameters

Name Type Required Description
refreshToken String Yes The user's refresh token.

Responses

Status Code Description Content
200 OK Token refreshed successfully. 
{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
403 Forbidden Invalid or expired refresh token. 
{
    "error": "Invalid refresh token"
}

User Management

Get User Profile

GET /api/v1/users/me

Retrieves the profile information for the currently authenticated user.

Requires Authentication: Bearer Token

Responses

Status Code Description Content
200 OK User profile retrieved. 
{
    "id": "user-12345",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "createdAt": "2023-10-27T10:00:00Z"
}
401 Unauthorized Authentication token is missing or invalid. 
{
    "error": "Authentication required"
}

Update User Profile

PUT /api/v1/users/me

Updates the profile information for the currently authenticated user.

Requires Authentication: Bearer Token

Parameters

Name Type Required Description
name String No The user's new name.
email String No The user's new email address.

Responses

Status Code Description Content
200 OK User profile updated successfully. 
{
    "id": "user-12345",
    "name": "Jane Doe Updated",
    "email": "jane.doe.updated@example.com",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T11:30:00Z"
}
400 Bad Request Invalid input data. 
{
    "error": "Invalid email format"
}
401 Unauthorized Authentication token is missing or invalid. 
{
    "error": "Authentication required"
}

Product Endpoints

List Products

GET /api/v1/products

Retrieves a list of available products. Supports pagination and filtering.

Query Parameters

Name Type Required Description
page Integer No Page number for pagination (default: 1).
limit Integer No Number of items per page (default: 10).
category String No Filter products by category.

Responses

Status Code Description Content
200 OK List of products. 
{
    "data": [
        {
            "id": "prod-abcde",
            "name": "Wireless Mouse",
            "price": 25.99,
            "category": "Electronics",
            "stock": 150
        },
        {
            "id": "prod-fghij",
            "name": "Mechanical Keyboard",
            "price": 79.99,
            "category": "Electronics",
            "stock": 75
        }
    ],
    "pagination": {
        "currentPage": 1,
        "totalPages": 5,
        "totalItems": 50,
        "itemsPerPage": 10
    }
}

Order Processing

Create Order

POST /api/v1/orders

Creates a new order for the authenticated user.

Requires Authentication: Bearer Token

Parameters

Name Type Required Description
items Array of Objects Yes An array of items to include in the order. Each object should have productId and quantity.
shippingAddress Object Yes The shipping address for the order.

Responses

Status Code Description Content
201 Created Order created successfully. 
{
    "id": "order-xyz789",
    "userId": "user-12345",
    "status": "Pending",
    "totalAmount": 105.98,
    "createdAt": "2023-10-27T12:00:00Z"
}
400 Bad Request Invalid order details or insufficient stock. 
{
    "error": "One or more items are out of stock or invalid."
}
401 Unauthorized Authentication token is missing or invalid. 
{
    "error": "Authentication required"
}

Payment Gateway

Process Payment

POST /api/v1/payments/process

Processes a payment for an existing order.

Requires Authentication: Bearer Token

Parameters

Name Type Required Description
orderId String Yes The ID of the order to pay for.
paymentMethod String Yes The payment method (e.g., 'credit_card', 'paypal').
paymentDetails Object Yes Details of the payment method (e.g., card number, expiry, CVV).

Responses

Status Code Description Content
200 OK Payment processed successfully. 
{
    "paymentId": "pay-abcdef123",
    "orderId": "order-xyz789",
    "status": "Completed",
    "transactionTime": "2023-10-27T12:15:00Z"
}
400 Bad Request Invalid payment details or order not found. 
{
    "error": "Invalid payment details provided."
}
402 Payment Required Payment failed. 
{
    "error": "Payment declined by the bank."
}
401 Unauthorized Authentication token is missing or invalid. 
{
    "error": "Authentication required"
}