API.md

API Documentation

Base URL

http://localhost:8000/api/v1

Authentication

Most endpoints require authentication using JWT tokens.

Headers

Authorization: Bearer <access_token>

Endpoints

Health Check

GET /health

Check API health status.

Response

{
  "status": "healthy",
  "database": "healthy"
}

---

Authentication

POST /auth/login

Authenticate user and receive tokens.

Request Body

{
  "email": "user@example.com",
  "password": "password123"
}

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer"
}

POST /auth/refresh

Refresh access token.

Request Body

{
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer"
}

---

Users

POST /users

Create new user.

Request Body

{
  "email": "user@example.com",
  "username": "username",
  "password": "StrongPass123!"
}

Response (201 Created)

{
  "id": 1,
  "email": "user@example.com",
  "username": "username",
  "is_active": true,
  "is_superuser": false,
  "created_at": "2024-01-01T00:00:00",
  "updated_at": "2024-01-01T00:00:00"
}

GET /users/{user_id}

Get user by ID. Requires authentication.

Response

{
  "id": 1,
  "email": "user@example.com",
  "username": "username",
  "is_active": true,
  "is_superuser": false,
  "created_at": "2024-01-01T00:00:00",
  "updated_at": "2024-01-01T00:00:00"
}

---

Error Responses

400 Bad Request

{
  "detail": "Validation error message"
}

401 Unauthorized

{
  "detail": "Invalid authentication credentials"
}

404 Not Found

{
  "detail": "Resource not found"
}

500 Internal Server Error

{
  "detail": "Internal server error"
}

Rate Limiting

• 100 requests per minute per IP
• 1000 requests per hour per user

Pagination

List endpoints support pagination:

GET /users?skip=0&limit=10

Response Format

{
  "items": [...],
  "total": 100,
  "skip": 0,
  "limit": 10
}