Skip to content

api-reference.md

Latest commit

 

History

History
269 lines (214 loc) · 5.08 KB

api-reference.md

File metadata and controls

269 lines (214 loc) · 5.08 KB

API Reference

Management REST API

Base URL: http://localhost:8081/api/v1

Authentication

When an API key is configured, include it in requests via:

  • Header: X-API-Key: <key>
  • Query parameter: ?api_key=<key>

The /health endpoint does not require authentication.

Authentication Flow

sequenceDiagram
    participant C as Client
    participant API as Management API
    participant Auth as withAuth() Middleware

    C->>+API: GET /api/v1/routes
    API->>+Auth: Check authentication
    alt API key configured
        Auth->>Auth: Read X-API-Key header or api_key param
        alt Valid key
            Auth-->>API: Authorized
            API-->>C: 200 OK (route data)
        else Invalid / missing key
            Auth-->>API: Unauthorized
            API-->>C: 401 {"error": "unauthorized"}
        end
    else No API key configured
        Auth-->>-API: Pass through (no auth)
        API-->>-C: 200 OK (route data)
    end
Loading

Route Management Flow

sequenceDiagram
    participant Admin as Admin UI / CLI
    participant API as Management API
    participant Router as Router Engine

    Admin->>+API: POST /api/v1/routes {id, name, destinations}
    API->>API: Validate request (id + destinations required)
    alt Validation fails
        API-->>Admin: 400 {"error": "missing fields"}
    else Valid
        API->>+Router: AddRoute(route)
        alt Route ID already exists
            Router-->>API: Conflict
            API-->>Admin: 409 {"error": "already exists"}
        else New route
            Router-->>-API: Route added
            API-->>-Admin: 201 {route object}
        end
    end

    Admin->>+API: GET /api/v1/routes
    API->>+Router: GetRoutes()
    Router-->>-API: []Route
    API-->>-Admin: 200 [{route}, {route}, ...]

    Admin->>+API: DELETE /api/v1/routes/{id}
    API->>+Router: RemoveRoute(id)
    alt Route not found
        Router-->>API: Not found
        API-->>Admin: 404 {"error": "not found"}
    else Deleted
        Router-->>-API: Removed
        API-->>-Admin: 204 No Content
    end
Loading

Message Publish Flow

sequenceDiagram
    participant C as Client
    participant API as Management API
    participant B as Broker
    participant S as Subscriber

    C->>+API: POST /api/v1/publish/orders.new<br/>Body: {"orderId": "123"}
    API->>API: Parse JSON body
    alt Invalid JSON
        API-->>C: 400 {"error": "invalid JSON"}
    else Valid
        API->>API: Create message.Message from body
        API->>+B: Publish(ctx, "orders.new", msg)
        alt Broker error
            B-->>API: Error
            API-->>C: 500 {"error": "publish failed"}
        else Success
            B-->>-API: nil
            API-->>-C: 200 {"status":"published", "topic":"orders.new", "message_id":"..."}
        end
        B-)S: Deliver async to subscribers
    end
Loading

Health Check

GET /api/v1/health

Response 200 OK:

{
  "status": "healthy",
  "timestamp": "2025-01-01T00:00:00Z"
}

Server Info

GET /api/v1/info

Response 200 OK:

{
  "name": "simple-service-bus",
  "version": "1.0.0",
  "broker": "memory"
}

Configuration

GET /api/v1/config

Response 200 OK:

{
  "address": ":8081"
}

List Routes

GET /api/v1/routes

Response 200 OK:

[
  {
    "id": "route-1",
    "name": "Order Route",
    "description": "Routes orders to processing",
    "destinations": ["orders.process"],
    "priority": 10,
    "enabled": true
  }
]

Create Route

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

Request Body:

{
  "id": "route-1",
  "name": "Order Route",
  "description": "Routes orders to processing",
  "destinations": ["orders.process"],
  "priority": 10,
  "enabled": true
}
Field Type Required Description
id string yes Unique route identifier
name string no Human-readable name
description string no Route description
destinations string[] yes Target topics
priority int no Route priority (higher = first)
enabled bool no Whether the route is active

Response 201 Created:

{
  "id": "route-1",
  "name": "Order Route",
  "destinations": ["orders.process"],
  "priority": 10,
  "enabled": true
}

Errors:

  • 400 - Missing id or destinations
  • 409 - Route with that id already exists

Get Route

GET /api/v1/routes/{id}

Response 200 OK: Route object (same as list item)

Errors:

  • 404 - Route not found

Delete Route

DELETE /api/v1/routes/{id}

Response 204 No Content

Errors:

  • 404 - Route not found

Publish Message

POST /api/v1/publish/{topic}
Content-Type: application/json

Request Body: Any valid JSON (becomes the message body)

Response 200 OK:

{
  "status": "published",
  "topic": "orders.new",
  "message_id": "550e8400-e29b-41d4-a716-446655440000"
}

Errors:

  • 400 - Invalid JSON body
  • 500 - Publish failed (e.g., broker not connected)