Skip to content

control-api.md

Latest commit

 

History

History
172 lines (123 loc) · 3.02 KB

control-api.md

File metadata and controls

172 lines (123 loc) · 3.02 KB
Raw

Control API

The Control API changes or inspects the state of the running server.

It does not rewrite the config file.

All endpoints are local runtime endpoints under __control.

Active State

GET   /__control/scenario
PATCH /__control/scenario

GET /__control/scenario

Returns the current active state as JSON.

Example response:

{
  "auth": "logged-in"
}

PATCH /__control/scenario

Validates all requested dimension/value pairs first, then updates the running active state.

Example request:

curl -s -X PATCH http://127.0.0.1:4545/__control/scenario \
  -H "Content-Type: application/json" \
  -d '{"auth":"expired"}'

Example success response:

{
  "auth": "expired"
}

Example error cases:

  • unknown dimension -> 400
  • unknown value -> 400

On validation failure, runtime state is not changed.

Scenario Discovery

GET /__control/scenarios
GET /__control/scenarios/:dimension/:value

GET /__control/scenarios

Returns machine-readable scenario metadata for all dimensions and values in the running snapshot.

Example response shape:

[
  {
    "dimension": "auth",
    "value": "expired",
    "title": "Expired session",
    "description": "JWT token expired",
    "tags": ["auth", "error"]
  }
]

GET /__control/scenarios/:dimension/:value

Returns machine-readable details for one scenario value.

Example:

curl -s http://127.0.0.1:4545/__control/scenarios/auth/expired

Example response shape:

{
  "dimension": "auth",
  "value": "expired",
  "title": "Expired session",
  "description": "JWT token expired",
  "tags": ["auth", "error"],
  "affectedRoutes": [
    {
      "route": "get-current-user",
      "method": "GET",
      "path": "/api/me",
      "baseStatus": 200,
      "scenarioStatus": 401
    }
  ]
}

affectedRoutes is derived from scenario overrides and base route lookup.

Profiles

GET  /__control/profiles
POST /__control/profile/apply

GET /__control/profiles

Returns machine-readable profile metadata from the running snapshot.

Example response shape:

[
  {
    "name": "auth-expired",
    "title": "Expired auth profile",
    "description": "Switches auth to expired for 401 responses."
  }
]

POST /__control/profile/apply

Applies a named profile to the running server.

Profile application is a full active-state replacement, not a patch.

Example request:

curl -s -X POST http://127.0.0.1:4545/__control/profile/apply \
  -H "Content-Type: application/json" \
  -d '{"profile":"auth-expired"}'

Example success response:

{
  "auth": "expired"
}

Example error cases:

  • unknown profile -> 400
  • invalid profile definition -> 400

On validation failure, runtime state is not changed.

Notes

  • Control API responses are JSON.
  • Discovery endpoints expose the immutable runtime snapshot.
  • State-changing endpoints mutate only the running active state.
  • CLI discovery commands should match the same semantics as these runtime endpoints.