API Endpoints Reference

This document outlines the available API endpoints, their methods, request parameters, and expected responses. Please ensure you have a valid API key for authentication.

Authentication

POST /auth/login

Authenticates a user and returns an access token.

Parameters (Request Body)

  • email (string, required): The user's email address.
  • password (string, required): The user's password.

Responses

  • 200 OK: Successfully authenticated. Returns an access token.
  • 401 Unauthorized: Invalid credentials.
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Users

GET /users

Retrieves a list of all users.

Query Parameters

  • limit (integer, optional): Maximum number of users to return.
  • offset (integer, optional): Number of users to skip.

Responses

  • 200 OK: Returns a list of user objects.
GET /users/{userId}

Retrieves a specific user by their ID.

Path Parameters

  • userId (string, required): The unique identifier of the user.

Responses

  • 200 OK: Returns the user object.
  • 404 Not Found: User not found.
POST /users

Creates a new user.

Parameters (Request Body)

  • name (string, required)
  • email (string, required)
  • password (string, required)

Responses

  • 201 Created: User created successfully.
  • 400 Bad Request: Invalid input data.

Products

GET /products

Retrieves a list of all available products.

Query Parameters

  • category (string, optional): Filter products by category.
  • search (string, optional): Search term for product names or descriptions.

Responses

  • 200 OK: Returns a list of product objects.
GET /products/{productId}

Retrieves details for a specific product.

Path Parameters

  • productId (string, required): The unique identifier of the product.

Responses

  • 200 OK: Returns the product object.
  • 404 Not Found: Product not found.

Orders

POST /orders

Creates a new order.

Parameters (Request Body)

  • items (array, required): An array of product IDs and quantities.
  • shippingAddress (object, required)

Responses

  • 201 Created: Order placed successfully. Returns the order object.
  • 400 Bad Request: Invalid order details or items.

Webhooks

POST /webhooks

Registers a webhook endpoint to receive real-time notifications for events.

Parameters (Request Body)

  • url (string, required): The URL to send notifications to.
  • events (array, required): List of events to subscribe to (e.g., "order.created", "product.updated").

Responses

  • 200 OK: Webhook registered successfully.
  • 400 Bad Request: Invalid URL or event type.