API Documentation

Version: v1 Base URL: https://api.yourapp.com/api/v1 Last Updated: 2025-01-15

Authentication

Overview

Our API uses JWT (JSON Web Tokens) for authentication.

Flow:

Login with email/password to get access token + refresh token
Include access token in Authorization header for all requests
Refresh access token when it expires using refresh token

Token Expiry:

Access token: 30 minutes
Refresh token: 7 days

Common Headers

All requests should include:

  Content-Type: application/json
Authorization: Bearer {access_token}

Response Formats

Success Response

Single Resource:

  {
  "id": 123,
  "email": "user@example.com",
  "created_at": "2025-01-15T10:30:00Z"
}

List of Resources:

  {
  "items": [...],
  "total": 50,
  "page": 1,
  "page_size": 20,
  "has_next": true
}

Action Completed:

  {
  "status": "success",
  "message": "Order cancelled successfully",
  "order_id": 456
}

Error Response

  {
  "detail": "User with email user@example.com already exists",
  "error_code": "EMAIL_EXISTS"
}

Error Codes

Status Code	Meaning	Common Causes
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Resource deleted successfully
400	Bad Request	Business logic error, invalid data
401	Unauthorized	Invalid or missing token
403	Forbidden	Valid token but insufficient permissions
404	Not Found	Resource doesn’t exist
422	Unprocessable Entity	Validation error (invalid input format)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)

Rate Limiting

Authenticated users: 100 requests per minute
Unauthenticated: 20 requests per minute

Headers:

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

Endpoints

Authentication Endpoints

Authenticate user and receive access + refresh tokens.

Endpoint: POST /auth/login

Authentication: None required

Request Body:

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

Response (200 OK):

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

Errors:

401 Unauthorized: Invalid email or password

Example cURL:

  curl -X POST https://api.yourapp.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "securepassword123"
  }'

Refresh Token

Get a new access token using refresh token.

Endpoint: POST /auth/refresh

Authentication: None required

Request Body:

  {
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

  {
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Errors:

401 Unauthorized: Invalid or expired refresh token

Get Current User

Retrieve currently authenticated user’s information.

Endpoint: GET /auth/me

Authentication: Required

Response (200 OK):

  {
  "id": 123,
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "is_admin": false,
  "created_at": "2025-01-10T08:00:00Z"
}

Errors:

401 Unauthorized: Invalid or missing token

Example cURL:

  curl -X GET https://api.yourapp.com/api/v1/auth/me \
  -H "Authorization: Bearer {access_token}"

Users Endpoints

Create User

Create a new user (admin only).

Endpoint: POST /users

Authentication: Required (admin only)

Request Body:

  {
  "email": "newuser@example.com",
  "full_name": "New User",
  "password": "securepassword123"
}

Response (201 Created):

  {
  "id": 124,
  "email": "newuser@example.com",
  "full_name": "New User",
  "is_active": true,
  "is_admin": false,
  "created_at": "2025-01-15T10:30:00Z"
}

Errors:

401 Unauthorized: Not authenticated
403 Forbidden: Not an admin
400 Bad Request: Email already exists
422 Unprocessable Entity: Invalid email format, password too short

Example cURL:

  curl -X POST https://api.yourapp.com/api/v1/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "full_name": "New User",
    "password": "securepassword123"
  }'

List Users

Retrieve paginated list of users.

Endpoint: GET /users

Authentication: Required

Query Parameters:

page (optional): Page number (default: 1)
page_size (optional): Items per page (default: 20, max: 100)
is_active (optional): Filter by active status (true/false)

Response (200 OK):

  {
  "items": [
    {
      "id": 123,
      "email": "user@example.com",
      "full_name": "John Doe",
      "is_active": true,
      "created_at": "2025-01-10T08:00:00Z"
    },
    ...
  ],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "has_next": true
}

Errors:

401 Unauthorized: Not authenticated

Example cURL:

  curl -X GET "https://api.yourapp.com/api/v1/users?page=1&page_size=20&is_active=true" \
  -H "Authorization: Bearer {access_token}"

Get User by ID

Retrieve a specific user.

Endpoint: GET /users/{user_id}

Authentication: Required

Path Parameters:

user_id: User ID

Response (200 OK):

  {
  "id": 123,
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "is_admin": false,
  "created_at": "2025-01-10T08:00:00Z",
  "updated_at": "2025-01-12T14:20:00Z"
}

Errors:

401 Unauthorized: Not authenticated
404 Not Found: User not found

Example cURL:

  curl -X GET https://api.yourapp.com/api/v1/users/123 \
  -H "Authorization: Bearer {access_token}"

Update User

Update user details.

Endpoint: PATCH /users/{user_id}

Authentication: Required (own profile or admin)

Path Parameters:

user_id: User ID

Request Body (all fields optional):

  {
  "full_name": "Updated Name",
  "email": "newemail@example.com"
}

Response (200 OK):

  {
  "id": 123,
  "email": "newemail@example.com",
  "full_name": "Updated Name",
  "is_active": true,
  "is_admin": false,
  "created_at": "2025-01-10T08:00:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}

Errors:

401 Unauthorized: Not authenticated
403 Forbidden: Cannot update other user’s profile
404 Not Found: User not found
400 Bad Request: Email already in use

Example cURL:

  curl -X PATCH https://api.yourapp.com/api/v1/users/123 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Updated Name"
  }'

Delete User

Soft delete a user (admin only).

Endpoint: DELETE /users/{user_id}

Authentication: Required (admin only)

Path Parameters:

user_id: User ID

Response (204 No Content):

  No content

Errors:

401 Unauthorized: Not authenticated
403 Forbidden: Not an admin
404 Not Found: User not found

Example cURL:

  curl -X DELETE https://api.yourapp.com/api/v1/users/123 \
  -H "Authorization: Bearer {access_token}"

Orders Endpoints

Create Order

Create a new order (capture and process async).

Endpoint: POST /orders

Authentication: Required

Request Body:

  {
  "items": [
    {
      "product_id": 456,
      "quantity": 2
    },
    {
      "product_id": 789,
      "quantity": 1
    }
  ],
  "shipping_address": "123 Main St, City, Country"
}

Response (201 Created):

  {
  "id": 1001,
  "user_id": 123,
  "status": "pending",
  "total_amount": 0,
  "items": [
    {
      "product_id": 456,
      "quantity": 2,
      "unit_price": 0
    }
  ],
  "created_at": "2025-01-15T10:40:00Z"
}

Note: Order is created immediately with status: "pending". Background job will process it asynchronously (calculate total, check inventory, etc.). Total amount calculated after processing.

Errors:

401 Unauthorized: Not authenticated
400 Bad Request: Invalid product ID or quantity
422 Unprocessable Entity: Missing required fields

Example cURL:

  curl -X POST https://api.yourapp.com/api/v1/orders \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"product_id": 456, "quantity": 2}
    ],
    "shipping_address": "123 Main St"
  }'

List Orders

Retrieve paginated list of orders for current user.

Endpoint: GET /orders

Authentication: Required

Query Parameters:

page (optional): Page number (default: 1)
page_size (optional): Items per page (default: 20, max: 100)
status (optional): Filter by status (pending, processing, completed, failed)

Response (200 OK):

  {
  "items": [
    {
      "id": 1001,
      "user_id": 123,
      "status": "completed",
      "total_amount": 149.99,
      "created_at": "2025-01-15T10:40:00Z",
      "updated_at": "2025-01-15T10:42:00Z"
    },
    ...
  ],
  "total": 25,
  "page": 1,
  "page_size": 20,
  "has_next": true
}

Errors:

401 Unauthorized: Not authenticated

Example cURL:

  curl -X GET "https://api.yourapp.com/api/v1/orders?status=completed" \
  -H "Authorization: Bearer {access_token}"

Get Order by ID

Retrieve a specific order.

Endpoint: GET /orders/{order_id}

Authentication: Required

Path Parameters:

order_id: Order ID

Response (200 OK):

  {
  "id": 1001,
  "user_id": 123,
  "status": "completed",
  "total_amount": 149.99,
  "shipping_address": "123 Main St, City, Country",
  "items": [
    {
      "id": 5001,
      "product_id": 456,
      "product_name": "Product A",
      "quantity": 2,
      "unit_price": 49.99
    },
    {
      "id": 5002,
      "product_id": 789,
      "product_name": "Product B",
      "quantity": 1,
      "unit_price": 50.01
    }
  ],
  "created_at": "2025-01-15T10:40:00Z",
  "updated_at": "2025-01-15T10:42:00Z"
}

Errors:

401 Unauthorized: Not authenticated
403 Forbidden: Cannot view other user’s orders
404 Not Found: Order not found

Example cURL:

  curl -X GET https://api.yourapp.com/api/v1/orders/1001 \
  -H "Authorization: Bearer {access_token}"

How to Keep This Updated

IMPORTANT: This document MUST be updated whenever API changes are made.

When to Update

✅ Adding new endpoint
✅ Changing request/response schema
✅ Adding/removing query parameters
✅ Changing error codes
✅ Modifying authentication requirements

Process

Before implementing: Document the endpoint here first
During PR review: Verify documentation matches implementation
After merge: Ensure documentation is in sync

Template for New Endpoints

  ### [Endpoint Name]

[Brief description of what this endpoint does]

**Endpoint**: `[METHOD] /path`

**Authentication**: Required / Not required

**Request Body** (if POST/PUT/PATCH):
```json
{
  "field": "value"
}

Response ([STATUS CODE]):

  {
  "response": "data"
}

Errors:

CODE: Description

Example cURL:

  curl -X METHOD URL \
  -H "Authorization: Bearer {token}" \
  -d '{"data": "here"}'

  
---

## OpenAPI/Swagger Documentation

For interactive API documentation, visit:

**Development**: `http://localhost:8000/docs`
**Staging**: `https://staging.yourapp.com/docs`
**Production**: `https://api.yourapp.com/docs`

FastAPI automatically generates interactive documentation from your code.

---

## Changelog

| Date | Version | Changes |
|------|---------|---------|
| 2025-01-15 | v1 | Initial API documentation |

---

## Support

For API questions or issues:
- **Slack**: #dev-team
- **Email**: dev@yourapp.com
- **GitHub**: Create issue in repository

---

**Last Updated**: 2025-01-15
**Maintained by**: Development Team

API Patterns

API Documentation

Table of Contents link

Authentication link

Overview link

Common Headers link

Response Formats link

Success Response link

Error Response link

Error Codes link

Rate Limiting link

Endpoints link

Authentication Endpoints link

Login link

Refresh Token link

Get Current User link

Users Endpoints link

Create User link

List Users link

Get User by ID link

Update User link

Delete User link

Orders Endpoints link

Create Order link

List Orders link

Get Order by ID link

How to Keep This Updated link

When to Update link

Process link

Template for New Endpoints link

Table of Contents

Authentication

Overview

Common Headers

Response Formats

Success Response

Error Response

Error Codes

Rate Limiting

Endpoints

Authentication Endpoints

Login

Refresh Token

Get Current User

Users Endpoints

Create User

List Users

Get User by ID

Update User

Delete User

Orders Endpoints

Create Order

List Orders

Get Order by ID

How to Keep This Updated

When to Update

Process

Template for New Endpoints