DataHub API Documentation

A comprehensive REST API for managing users, products, and orders. Version 2.0

Introduction

Welcome to the DataHub API! This API allows you to programmatically access and manage your data. Our API is organized around REST principles and uses standard HTTP response codes.

Base URL: https://api.datahub.example.com/v2

Format: All responses are returned in JSON format.

Authentication

🔐 API Key Required

All API requests require an API key to be included in the header.

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY_HERE

Example request:

curl -H "Authorization: Bearer sk_live_abc123xyz" \ https://api.datahub.example.com/v2/users

Users

GET /users

Retrieve a list of all users.

Query Parameters
Parameter Type Required Description
limit integer optional Number of results (default: 10, max: 100)
offset integer optional Pagination offset (default: 0)
sort string optional Sort by field (created_at, name)
Response (200 OK)
{ "data": [ { "id": "usr_123abc", "name": "John Doe", "email": "john@example.com", "created_at": "2024-01-15T10:30:00Z", "status": "active" } ], "meta": { "total": 150, "limit": 10, "offset": 0 } }

POST /users

Create a new user.

Request Body
Field Type Required Description
name string required User's full name
email string required User's email address
role string optional User role (admin, user, guest)
Response (201 Created)
{ "id": "usr_456def", "name": "Jane Smith", "email": "jane@example.com", "role": "user", "created_at": "2024-12-14T15:45:00Z" }

GET /users/:id

Retrieve a specific user by ID.

Response (200 OK)
{ "id": "usr_123abc", "name": "John Doe", "email": "john@example.com", "role": "admin", "created_at": "2024-01-15T10:30:00Z", "last_login": "2024-12-14T09:20:00Z" }

DELETE /users/:id

Delete a user by ID.

Response (204 No Content)

Products

GET /products

Retrieve all products.

Response (200 OK)
{ "data": [ { "id": "prd_789ghi", "name": "Premium Widget", "price": 49.99, "currency": "USD", "stock": 150, "category": "electronics" } ] }

POST /products

Create a new product.

Request Body
{ "name": "New Product", "price": 29.99, "currency": "USD", "stock": 100, "category": "electronics", "description": "Product description here" }

Orders

GET /orders

Retrieve all orders.

Response (200 OK)
{ "data": [ { "id": "ord_321xyz", "user_id": "usr_123abc", "total": 149.97, "status": "completed", "created_at": "2024-12-10T14:20:00Z", "items": [ { "product_id": "prd_789ghi", "quantity": 3, "price": 49.99 } ] } ] }

POST /orders

Create a new order.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code Meaning
200 OK - Request succeeded
201 Created - Resource created successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing API key
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error
Error Response Format
{ "error": { "code": "invalid_request", "message": "Email address is required", "param": "email" } }

Rate Limits

API requests are limited to prevent abuse:

  • Standard: 1000 requests per hour
  • Premium: 5000 requests per hour

Rate limit info is included in response headers:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1702566000