Admin API

Joynare Nexus provides a set of read-only administrative endpoints designed to expose the system state to monitoring dashboards and developer tooling.

These endpoints are registered on the Design API port (configured in routes/server.yaml, default 9092) to isolate internal administration and diagnostic services from standard client-facing business logic traffic. All administrative endpoints automatically include standard CORS headers (e.g., Access-Control-Allow-Origin: *) and support preflight requests.

Security & Authentication

The Admin API endpoints share the security configuration of the Design API. By default, these endpoints are fully unauthenticated for convenience during local development. However, they can be secured by specifying an apikey value under the designApi configuration in routes/server.yaml:

server:
  designApi:
    enabled: true
    port: 9092
    apikey: "your-secure-api-key"

When an apikey is configured:

• All requests to /api/admin/* must supply a matching X-API-Key: your-secure-api-key header.
• Requests missing or containing a mismatched API Key will fail with 401 Unauthorized status.
• CORS preflight OPTIONS requests will continue to return 200 OK without requiring the X-API-Key header, permitting frontend applications to dynamically negotiate connections.

---

1. Get Metrics (GET /api/admin/metrics)

Exposes high-level performance and request stats aggregated over the last 24 hours, alongside time-series request buckets.

• Method: GET
• Endpoint: /api/admin/metrics
• Query Parameters: None
• Response Format:
  • If the database-backed metrics system is active: returns complete 24-hour aggregates and a time-series array divided into 6 4-hour historical buckets (ordered oldest to newest).
  • If no database is configured: returns system metadata (flow and route counts) while marking metricsAvailable as false.

Example Response (Metrics Enabled)

{
  "totalRequests": 1042,
  "errorCount": 12,
  "avgLatencyMs": 14.52,
  "activeRoutes": 8,
  "activeFlows": 14,
  "metricsAvailable": true,
  "timeSeries": [
    { "time": "03:17", "requests": 120, "errors": 2 },
    { "time": "07:17", "requests": 240, "errors": 3 },
    { "time": "11:17", "requests": 182, "errors": 1 },
    { "time": "15:17", "requests": 210, "errors": 4 },
    { "time": "19:17", "requests": 140, "errors": 0 },
    { "time": "23:17", "requests": 150, "errors": 2 }
  ]
}

Example Response (Metrics Disabled)

{
  "totalRequests": 0,
  "errorCount": 0,
  "avgLatencyMs": 0,
  "activeRoutes": 8,
  "activeFlows": 14,
  "metricsAvailable": false,
  "timeSeries": []
}

---

2. Get Logs (GET /api/admin/logs)

Streams system logs in reverse-chronological order (newest log entries first) by reading and parsing the server's local log file at logs/nexus.log. It supports parsing both structured JSON and plain-text slog key-value formats.

• Method: GET
• Endpoint: /api/admin/logs
• Query Parameters:
  • limit (integer, default 200, range 1-1000): Maximum number of log lines to return.
  • offset (integer, default 0): Pagination offset.
  • level (string, case-insensitive, e.g., ALL, DEBUG, INFO, WARN, ERROR): Filter logs by severity level.
  • search (string, case-insensitive): Text query to search log messages and timestamps.

Example Response

{
  "total": 354,
  "logs": [
    {
      "id": "log-0",
      "time": "11:15:30",
      "level": "INFO",
      "message": "server started successfully port=9090"
    },
    {
      "id": "log-1",
      "time": "11:15:32",
      "level": "WARN",
      "message": "slow query detected duration_ms=230"
    }
  ]
}

---

3. Get Inbound Routes (GET /api/admin/routes)

Lists all routes configured within the ESB, grouped and resolved under their base paths, detailing their endpoints and flow targets.

• Method: GET
• Endpoint: /api/admin/routes
• Query Parameters: None

Example Response

[
  {
    "name": "ProcessCustomer",
    "path": "/api/v1/customers/process",
    "method": "POST",
    "flow": "examples:ProcessCustomer",
    "enabled": true,
    "requireAuth": false
  },
  {
    "name": "GetCustomer",
    "path": "/api/v1/customers/:id",
    "method": "GET",
    "flow": "customers:GetCustomer",
    "enabled": true,
    "requireAuth": true
  }
]

---

4. Get Connections (GET /api/admin/connections)

Lists configured external resource connections loaded from the system's config/connections.yaml file.

IMPORTANT

To prevent exposure of sensitive credentials, the database connection strings (DSN) are automatically masked using robust regular expressions (supporting standard URL formats and key-value formats) before being sent to the client.

• Method: GET
• Endpoint: /api/admin/connections
• Query Parameters: None

Example Response

[
  {
    "name": "main_postgres",
    "type": "database",
    "driver": "postgres",
    "dsn": "postgresql://postgres:****@localhost:5432/nexus_db?sslmode=disable"
  },
  {
    "name": "billing_db",
    "type": "database",
    "driver": "mysql",
    "dsn": "root:****@tcp(127.0.0.1:3306)/billing?parseTime=true"
  }
]

---

5. Background Schedules API

A set of endpoints designed to read, create, update, toggle, trigger, and delete dynamic background execution schedules.

A. List Schedules (GET /api/admin/schedules)

Retrieves a combined list of active static (YAML) and database-backed dynamic schedules, including historical statistics and next run predictions.

• Method: GET
• Endpoint: /api/admin/schedules
• Query Parameters: None

B. Save Dynamic Schedule (POST /api/admin/schedules)

Creates a new database task or updates an existing one if the id field matches. Saving a schedule automatically triggers a thread-safe reload of the background triggers.

• Method: POST
• Endpoint: /api/admin/schedules
• Request Body: JSON representation of the schedule definition (containing name, service, cron or interval, input, and optional enabled flag).

C. Toggle Schedule Status (POST /api/admin/schedules/{id}/toggle)

Flips the enabled state of a dynamic database schedule.

• Method: POST
• Endpoint: /api/admin/schedules/{id}/toggle
• Request Body (Optional): {"enabled": false} to explicitly enable/disable. If empty, the endpoint automatically toggles the opposite of the current active in-memory state.

D. Manual Execute (POST /api/admin/schedules/{id}/run)

Instantly executes a task on a detached background goroutine for testing or validation, without affecting its scheduled cron timeline.

• Method: POST
• Endpoint: /api/admin/schedules/{id}/run

E. Delete Schedule (DELETE /api/admin/schedules/{id})

Removes a task permanently from the database and stops background workers immediately.

• Method: DELETE
• Endpoint: /api/admin/schedules/{id}

---

6. Dynamic Port Listeners API

A set of administrative endpoints designed to retrieve active port configurations, launch new HTTP or HTTPS port listeners on hot-reloading sockets, and cleanly stop active network ports at runtime.

A. List Port Listeners (GET /api/admin/listeners)

Retrieves the full list of configured port listeners mapped to their current socket server status.

• Method: GET
• Endpoint: /api/admin/listeners
• Query Parameters: None
• Response Format: Returns an array of configurations. Status will be dynamically reported as "active" if the TCP server is actively listening, or "inactive" otherwise.

Example Response

[
  {
    "port": 9090,
    "protocol": "http",
    "status": "active"
  },
  {
    "port": 9443,
    "protocol": "https",
    "certFile": "/certs/server.crt",
    "keyFile": "/certs/server.key",
    "status": "active"
  }
]

B. Add Port Listener (POST /api/admin/listeners)

Creates a new network port configuration, binds a new socket server to listen on the selected port dynamically at runtime, and persists the configuration securely to routes/server.yaml.

• Method: POST
• Endpoint: /api/admin/listeners
• Request Body (JSON):
  • port (integer, required): Target TCP port (1-65535).
  • protocol (string, required): Enum "http" or "https".
  • certFile (string, optional): SSL certificate path (required for HTTPS).
  • keyFile (string, optional): SSL private key path (required for HTTPS).

Example Request

{
  "port": 8081,
  "protocol": "http"
}

Example Response

{
  "port": 8081,
  "protocol": "http",
  "status": "active"
}

C. Delete Port Listener (DELETE /api/admin/listeners/{port})

Gracefully terminates the runtime socket listener running on the specified port, and purges it from the list of configurations in routes/server.yaml.

• Method: DELETE
• Endpoint: /api/admin/listeners/{port}
• Path Parameters:
  • port (integer, required): The target TCP port number.

Example Response

{
  "status": "success",
  "message": "Listener stopped and removed successfully"
}