Skip to content

API.md

Latest commit

 

History

History
417 lines (326 loc) · 6.06 KB

API.md

File metadata and controls

417 lines (326 loc) · 6.06 KB
Raw

API Documentation

Base URL

http://localhost:8080

Swagger UI

Interactive API docs are available at:

http://localhost:8080/swagger/index.html

To regenerate swagger docs after modifying annotations:

make swagger

Authentication

Most /api/v1/ endpoints require a JWT token in the Authorization header:

Authorization: Bearer <token>

Token Flow

  1. Register or Login to get an access token and refresh token
  2. Use the access token in the Authorization header for protected endpoints
  3. When the access token expires, call /auth/refresh with the refresh token
  4. Refresh tokens are single-use and stored in the database

Token Lifetimes

Token Lifetime Storage
Access Token 15 minutes Client (localStorage/cookie)
Refresh Token 7 days Database (opaque, hashed)

Responses

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Endpoints

Health Check

GET /health

Response:

{"status": "ok"}

Readiness Check

GET /ready

Response:

{"status": "ready"}

Authentication

Register

POST /api/v1/auth/register

Request:

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "John Doe"
}

Response (201):

{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4",
    "expires_in": 900,
    "token_type": "Bearer"
  }
}

Login

POST /api/v1/auth/login

Request:

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

Response (200):

{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4",
    "expires_in": 900,
    "token_type": "Bearer"
  }
}

Refresh Token

POST /api/v1/auth/refresh

Request:

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4"
}

Response (200):

{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "bmV3IHJlZnJlc2ggdG9rZW4",
    "expires_in": 900,
    "token_type": "Bearer"
  }
}

Logout

POST /api/v1/auth/logout

Request:

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4"
}

Response (200):

{
  "success": true,
  "data": {
    "message": "logged out successfully"
  }
}

Get Current User

GET /api/v1/auth/sessions/me

Requires Authorization: Bearer <token>.

Response (200):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "is_active": true
  }
}

Logout All Sessions

POST /api/v1/auth/sessions/logout-all

Requires Authorization: Bearer <token>.

Revokes all refresh tokens for the authenticated user.

Response (200):

{
  "success": true,
  "data": {
    "message": "all sessions terminated"
  }
}

Todos

All todo endpoints require Authorization: Bearer <token>.

Create Todo

POST /api/v1/todos

Request:

{
  "title": "Buy groceries",
  "description": "Milk, eggs, bread"
}

Response (201):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Buy groceries",
    "description": "Milk, eggs, bread",
    "completed": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

List Todos

GET /api/v1/todos?page=1&per_page=20

Response (200):

{
  "success": true,
  "data": {
    "todos": [...],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

Get Todo

GET /api/v1/todos/{id}

Response (200):

{
  "success": true,
  "data": {
    "id": "...",
    "title": "...",
    "description": "...",
    "completed": false,
    "created_at": "...",
    "updated_at": "..."
  }
}

Update Todo

PUT /api/v1/todos/{id}

Request:

{
  "title": "Updated title",
  "description": "Updated description"
}

Delete Todo

DELETE /api/v1/todos/{id}

Response (200):

{"success": true}

Complete Todo

PATCH /api/v1/todos/{id}/complete

Search Todos

GET /api/v1/todos/search?q=groceries&page=1&per_page=20

Authorization (RBAC)

All authorization endpoints require Authorization: Bearer <token>.

Roles

Method Endpoint Description
POST /api/v1/auth/roles Create a role
GET /api/v1/auth/roles List roles
GET /api/v1/auth/roles/{id} Get a role
PUT /api/v1/auth/roles/{id} Update a role
DELETE /api/v1/auth/roles/{id} Delete a role

Permissions

Method Endpoint Description
POST /api/v1/auth/permissions Create a permission
GET /api/v1/auth/permissions List permissions
GET /api/v1/auth/permissions/{id} Get a permission
PUT /api/v1/auth/permissions/{id} Update a permission
DELETE /api/v1/auth/permissions/{id} Delete a permission

User-Role Assignments

Method Endpoint Description
POST /api/v1/auth/users/{userId}/roles Assign role to user
DELETE /api/v1/auth/users/{userId}/roles/{roleId} Remove role from user
GET /api/v1/auth/users/{userId}/roles Get user roles

Role-Permission Assignments

Method Endpoint Description
POST /api/v1/auth/roles/{roleId}/permissions Assign permission to role
DELETE /api/v1/auth/roles/{roleId}/permissions/{permissionId} Remove permission from role
GET /api/v1/auth/roles/{roleId}/permissions Get role permissions

Permission Check

POST /api/v1/auth/check-permission

Request:

{
  "resource": "todos",
  "action": "create"
}

Response (200):

{
  "success": true,
  "data": {
    "allowed": true
  }
}