Skip to content

API.md

Latest commit

 

History

History
375 lines (315 loc) · 5.95 KB

API.md

File metadata and controls

375 lines (315 loc) · 5.95 KB
Raw

API Documentation

Complete API reference for the Flask AWS Backend application.

Base URL

http://localhost:5000/api/v1  (Development)
https://api.example.com/api/v1  (Production)

Authentication

Most endpoints require authentication using JWT (JSON Web Tokens).

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "message": "Operation successful",
  "data": { ... }
}

Error Response

{
  "success": false,
  "message": "Error message",
  "errors": { ... }
}

Paginated Response

{
  "success": true,
  "message": "Success",
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 100,
    "total_pages": 10,
    "has_next": true,
    "has_prev": false
  }
}

Endpoints

Health Check

GET /health

Basic health check endpoint.

Response

{
  "success": true,
  "message": "Application is running",
  "data": {
    "status": "healthy",
    "version": "1.0.0"
  }
}

GET /health/detailed

Detailed health check including database and cache status.

Response

{
  "success": true,
  "message": "All systems operational",
  "data": {
    "application": "healthy",
    "database": "healthy",
    "cache": "healthy"
  }
}

Authentication

POST /auth/register

Register a new user account.

Request Body

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

Response (201 Created)

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "username": "username",
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    },
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbG...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbG..."
  }
}

POST /auth/login

Authenticate user and receive access tokens.

Request Body

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

Response (200 OK)

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": { ... },
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbG...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbG..."
  }
}

POST /auth/refresh

Refresh access token using refresh token.

Headers

Authorization: Bearer <refresh_token>

Response (200 OK)

{
  "success": true,
  "message": "Token refreshed successfully",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbG..."
  }
}

Users

GET /users/me

Get current authenticated user profile.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "message": "User profile retrieved",
  "data": {
    "id": 1,
    "email": "user@example.com",
    "username": "username",
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

PUT /users/me

Update current user profile.

Headers

Authorization: Bearer <access_token>

Request Body

{
  "username": "new_username"
}

Response (200 OK)

{
  "success": true,
  "message": "User profile updated successfully",
  "data": { ... }
}

Items

GET /items

Get paginated list of items.

Headers

Authorization: Bearer <access_token>

Query Parameters

  • page (integer, default: 1) - Page number
  • per_page (integer, default: 10, max: 100) - Items per page

Response (200 OK)

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "name": "Item Name",
      "description": "Item description",
      "price": 99.99,
      "user_id": 1,
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    }
  ],
  "pagination": { ... }
}

GET /items/:id

Get a specific item by ID.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Item Name",
    "description": "Item description",
    "price": 99.99,
    "user_id": 1,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

POST /items

Create a new item.

Headers

Authorization: Bearer <access_token>

Request Body

{
  "name": "Item Name",
  "description": "Item description",
  "price": 99.99
}

Response (201 Created)

{
  "success": true,
  "message": "Item created successfully",
  "data": { ... }
}

PUT /items/:id

Update an existing item.

Headers

Authorization: Bearer <access_token>

Request Body

{
  "name": "Updated Name",
  "description": "Updated description",
  "price": 149.99
}

Response (200 OK)

{
  "success": true,
  "message": "Item updated successfully",
  "data": { ... }
}

DELETE /items/:id

Delete an item.

Headers

Authorization: Bearer <access_token>

Response (204 No Content)

{
  "success": true,
  "message": "Item deleted successfully"
}

Error Codes

Status Code Description
200 OK - Request successful
201 Created - Resource created
204 No Content - Successful deletion
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error
503 Service Unavailable - Service temporarily unavailable

Rate Limiting

API endpoints are rate limited to prevent abuse:

  • Default: 100 requests per hour per IP
  • Authenticated: 1000 requests per hour per user

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000