Skip to content

API.md

Latest commit

 

History

History
441 lines (321 loc) · 7.67 KB

API.md

File metadata and controls

441 lines (321 loc) · 7.67 KB

API Documentation

Base URL

http://localhost:8080

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Endpoints

Public Endpoints

Register User

Create a new user account.

Request:

POST /api/v1/register
Content-Type: application/json

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

Validation Rules:

  • email: Must be a valid email format
  • username: 3-50 characters
  • password: Minimum 8 characters

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "username": "johndoe",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Error Responses:

  • 400 Bad Request: Validation error
  • 409 Conflict: Email already exists

Login

Authenticate and receive a JWT token.

Request:

POST /api/v1/login
Content-Type: application/json

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

Response: 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "johndoe",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Error Responses:

  • 400 Bad Request: Validation error
  • 401 Unauthorized: Invalid credentials

Protected Endpoints

All endpoints below require authentication.

Get All Users

Retrieve a paginated list of users.

Request:

GET /api/v1/users?page=1&per_page=10
Authorization: Bearer <token>

Query Parameters:

  • page (optional): Page number (default: 1)
  • per_page (optional): Items per page (default: 10)

Response: 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "username": "johndoe",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "per_page": 10,
  "total_pages": 10
}

Error Responses:

  • 401 Unauthorized: Missing or invalid token

Get User by ID

Retrieve a specific user by their ID.

Request:

GET /api/v1/users/{id}
Authorization: Bearer <token>

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "username": "johndoe",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Error Responses:

  • 401 Unauthorized: Missing or invalid token
  • 404 Not Found: User not found

Get Current User

Retrieve the authenticated user's information.

Request:

GET /api/v1/users/me
Authorization: Bearer <token>

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "username": "johndoe",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Error Responses:

  • 401 Unauthorized: Missing or invalid token

Update User

Update a user's information.

Request:

PUT /api/v1/users/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "newemail@example.com",
  "username": "newusername"
}

Note: All fields are optional. Only provide fields you want to update.

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newemail@example.com",
  "username": "newusername",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:01:00Z"
}

Error Responses:

  • 400 Bad Request: Validation error
  • 401 Unauthorized: Missing or invalid token
  • 404 Not Found: User not found
  • 409 Conflict: Email already exists

Delete User

Delete a user account.

Request:

DELETE /api/v1/users/{id}
Authorization: Bearer <token>

Response: 204 No Content

Error Responses:

  • 401 Unauthorized: Missing or invalid token
  • 404 Not Found: User not found

Health Check Endpoints

Health Check

Basic health check endpoint.

Request:

GET /health

Response: 200 OK

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z"
}

Readiness Check

Check if the service is ready to accept traffic (includes database connectivity check).

Request:

GET /ready

Response: 200 OK (empty body)

Error Responses:

  • 503 Service Unavailable: Database is not accessible

Liveness Check

Check if the service is alive.

Request:

GET /live

Response: 200 OK (empty body)

Error Response Format

All errors follow a consistent format:

{
  "error": "Error message describing what went wrong",
  "status": 400
}

Common HTTP Status Codes

  • 200 OK: Request succeeded
  • 204 No Content: Request succeeded with no response body
  • 400 Bad Request: Invalid request data or validation error
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Authenticated but not authorized
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate email)
  • 422 Unprocessable Entity: Request data is valid but cannot be processed
  • 500 Internal Server Error: Server error
  • 503 Service Unavailable: Service temporarily unavailable

Request Headers

Required for Protected Endpoints

Authorization: Bearer <jwt-token>

Recommended for All Requests

Content-Type: application/json
Accept: application/json

Response Headers

All responses include:

X-Request-ID: <unique-request-id>
Content-Type: application/json

Rate Limiting

Currently, no rate limiting is implemented. In production, consider adding rate limiting middleware.

Pagination

Endpoints that return lists support pagination:

  • page: Page number (starts at 1)
  • per_page: Number of items per page (max: 100)

Response includes:

  • data: Array of items
  • total: Total number of items
  • page: Current page
  • per_page: Items per page
  • total_pages: Total number of pages

Examples

cURL Examples

Register:

curl -X POST http://localhost:8080/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","username":"johndoe","password":"password123"}'

Login:

curl -X POST http://localhost:8080/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

Get Users (authenticated):

curl http://localhost:8080/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

JavaScript Examples

Using Fetch API:

// Register
const register = async () => {
  const response = await fetch('http://localhost:8080/api/v1/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'user@example.com',
      username: 'johndoe',
      password: 'password123'
    })
  });
  return await response.json();
};

// Login
const login = async () => {
  const response = await fetch('http://localhost:8080/api/v1/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'user@example.com',
      password: 'password123'
    })
  });
  const data = await response.json();
  return data.token;
};

// Get Users (authenticated)
const getUsers = async (token) => {
  const response = await fetch('http://localhost:8080/api/v1/users', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
};