API Reference

Authentication

Details on how to authenticate your API requests.

API Key Authentication

Requests must be authenticated using an API key, which should be passed in the Authorization header as a Bearer token.

Header: Authorization: Bearer YOUR_API_KEY
Important: Keep your API key confidential and do not expose it in client-side code.

OAuth 2.0

For more complex integrations requiring user authorization, we support OAuth 2.0. Refer to the OAuth 2.0 documentation for details.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses include a JSON payload with more details.

Common Status Codes:

  • 200 OK: Request successful.
  • 201 Created: Resource created successfully.
  • 400 Bad Request: Invalid request payload or parameters.
  • 401 Unauthorized: Authentication failed or missing.
  • 403 Forbidden: Insufficient permissions.
  • 404 Not Found: The requested resource could not be found.
  • 500 Internal Server Error: An unexpected server error occurred.
Example Error Response: 
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'userId' parameter is required.",
    "details": "userId (string)"
  }
}

Pagination

For collections that may contain many items, pagination is used to limit the amount of data returned in a single response.

Use the limit and offset query parameters to control pagination.

Query Parameters:

  • limit (integer): The maximum number of items to return per page. Default is 20. Maximum is 100.
  • offset (integer): The number of items to skip from the beginning of the list. Default is 0.

Pagination information is also included in the response headers:

Headers: 
X-Total-Count: 150
X-Limit: 20
X-Offset: 40

Users Resource

GET /users

Retrieve a list of users.

GET /users

Query Parameters:

  • status (string, optional): Filter users by status (e.g., 'active', 'inactive').

Response:

  • 200 OK: Returns an array of user objects.

Example user object:

{
  "id": "usr_123abc",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "status": "active",
  "createdAt": "2023-01-15T10:30:00Z"
}

Products Resource

GET /products

Retrieve a list of available products.

GET /products

Response:

  • 200 OK: Returns an array of product objects.

Example product object:

{
  "id": "prod_xyz789",
  "name": "Premium Widget",
  "description": "A high-quality widget for all your needs.",
  "price": 49.99,
  "currency": "USD",
  "stock": 150
}

GET /products/{productId}

Retrieve details for a specific product.

GET /products/{productId}

Path Parameters:

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

Response:

  • 200 OK: Returns the product object.
  • 404 Not Found: If the product with the given ID does not exist.

Orders Resource

POST /orders

Create a new order.

POST /orders

Request Body:

A JSON object containing order details.

{
  "userId": "usr_123abc",
  "items": [
    { "productId": "prod_xyz789", "quantity": 2 },
    { "productId": "prod_abc123", "quantity": 1 }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Anytown",
    "zipCode": "12345",
    "country": "USA"
  }
}

Response:

  • 201 Created: Returns the newly created order object.
  • 400 Bad Request: If the request body is invalid or required fields are missing.

Payments Resource

POST /payments

Initiate a payment for an order.

POST /payments

Request Body:

{
  "orderId": "ord_qwe987",
  "paymentMethodId": "pm_ Stripe_12345",
  "amount": 99.98,
  "currency": "USD"
}

Response:

  • 200 OK: Payment processed successfully. Returns payment details.
  • 402 Payment Required: Payment failed.

Notifications Resource

POST /notifications/send

Send a notification to a user.

POST /notifications/send

Request Body:

{
  "userId": "usr_123abc",
  "type": "email", // or "sms"
  "subject": "Your order has shipped!",
  "message": "Your order #ORD-5678 has been shipped and is expected to arrive in 3-5 business days."
}

Response:

  • 202 Accepted: Notification request accepted for processing.

Logs Resource

GET /logs

Retrieve API access logs.

GET /logs

Query Parameters:

  • startDate (datetime, optional): Filter logs from this date onwards (ISO 8601 format).
  • endDate (datetime, optional): Filter logs up to this date (ISO 8601 format).
  • level (string, optional): Filter logs by level (e.g., 'info', 'warn', 'error').

Response:

  • 200 OK: Returns an array of log entries.

Example log entry:

{
  "timestamp": "2023-10-27T14:55:10Z",
  "level": "info",
  "message": "User 'johndoe' accessed /products endpoint.",
  "userId": "usr_123abc",
  "ipAddress": "192.168.1.100"
}