Files
modelruimte/docs/API.md
robbertjanssen85andClaude Opus 4.7 5a16cb4c06 Add REST API, MCP server, OpenAPI/ReDoc docs, and client connect page
- /api/v1/* REST endpoints: health, model catalog (vehicles, functions,
  distributions, profiles, defaults), and simulate. Accepts functionCounts
  and/or functionBvoM2 (auto-converted via DEFAULT_BVO_PER_UNIT). Runs 2500
  Monte Carlo iterations by default; response adds a labeled `summary`
  (totalLengthM, totalAreaM2, per-vehicle + per-cluster) alongside the raw
  SimulationResult.
- /api/mcp Streamable-HTTP MCP endpoint (hand-rolled JSON-RPC 2.0, no new
  deps). Tools: get_model_info, list_vehicles/functions/distributions,
  get_delivery_profile, run_simulation.
- /api/v1/openapi.json + /api-docs: OpenAPI 3.0.3 spec rendered with ReDoc,
  themed to DMI palette + IBM Plex typography, DMI logo in the sidebar.
- /mcp-connect: DMI-styled page with copy-paste config blocks for Claude
  Code, Claude Desktop, Cursor, Codex CLI, Windsurf, and VS Code. MCP URL
  substituted from window.location.origin.
- Cover page gets an "Integraties" section with pill buttons linking to
  API-referentie and MCP instellen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 14:52:51 +02:00

6.0 KiB

Ruimtemodel Stadslogistiek — REST API

External systems can drive the Monte Carlo simulation engine and read the model catalog via a JSON REST API.

All endpoints:

  • Return application/json.
  • Send permissive CORS headers (Access-Control-Allow-Origin: *), so browser clients on any origin may call them.
  • Are read-only or idempotent — no authentication is required. The simulation endpoint caps numSimulations at 5000 to bound cost.

Base path: /api/v1

Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.0.3) Rendered reference: /api-docs (ReDoc) — also works in Redocly's hosted service and redocly preview-docs against the JSON URL.


Health

GET /api/v1/health

Response:

{ "status": "ok", "service": "ruimtemodel-api", "version": "1.0.0", "timestamp": "…" }

Model catalog

Full catalog

GET /api/v1/model

Returns vehicles, functions, distributions, periods, service levels, default cluster assignments, default cluster service levels, simulation parameters, loading-bay width, and all delivery profiles.

Individual resources

GET /api/v1/model/vehicles       → { vehicles: [...] }
GET /api/v1/model/functions      → { functions: [...] }
GET /api/v1/model/distributions  → { distributions: [...] }
GET /api/v1/model/profiles       → { profiles: { "F1_D7": {...}, … } }

The profiles endpoint also accepts query parameters:

GET /api/v1/model/profiles?function=F1                      # filter by function
GET /api/v1/model/profiles?distribution=D7                  # filter by distribution
GET /api/v1/model/profiles?function=F1&distribution=D7      # exact match → { key, profile }

Run simulation

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

Supply either number of units or BVO in m² per function (or mix the two — one mode per function). The simulation runs 2500 Monte Carlo iterations by default. Every other field has a sensible default.

Minimal body (units):

{ "functionCounts": { "F1": 362, "F2": 2, "F10": 5 } }

Minimal body (BVO):

{ "functionBvoM2": { "F1": 32580, "F10": 6250 } }

All fields:

{
  "functionCounts":        { "F1": 362 },                // units per function
  "functionBvoM2":         { "F10": 6250 },              // OR BVO (m²) per function
  "bvoPerUnit":            { "F1": 90 },                 // optional override for BVO→units conversion
  "clusterAssignments":    { "V1": 1, "V2": 1, "V3": 2 }, // optional, defaults to DEFAULT_CLUSTERS
  "clusterServiceLevels":  { "1": 0.95, "2": 0.95 },     // optional, defaults to 0.95 per cluster
  "numSimulations":        2500,                          // optional, default 2500, max 5000
  "vehicles":              [...],                         // optional override
  "functions":             [...],                         // optional override
  "distributions":         [...],                         // optional override
  "vehicleLengths":        { "V1": 2 },                   // optional override
  "deliveryDays":          { "D7": 6 },                   // optional override
  "deliveryProfiles":      { "F1_D7": {...} },            // optional override/merge
  "intervalMinutes":       10                             // optional override
}

At least one of functionCounts or functionBvoM2 must be provided. A single function may not appear in both — choose one mode per function.

Response:

{
  "summary": {
    "loadingBayWidthM": 3,
    "totalLengthM":     27.4,
    "totalAreaM2":      82.2,
    "vehicles": [
      {
        "vehicleId":           "V3",
        "vehicleName":         "Bestelwagen <3,5 ton (N1)",
        "vehicleLengthM":      8,
        "clusterId":           2,
        "totalArrivalsPerDay": 86.1,
        "requiredLengthM":     16,
        "requiredAreaM2":      48
      }
    ],
    "clusters": [
      { "clusterId": 1, "serviceLevel": 0.95, "vehicleIds": ["V1","V2"], "requiredLengthM": 0, "requiredAreaM2": 0 },
      { "clusterId": 2, "serviceLevel": 0.95, "vehicleIds": ["V3","V4","V5"], "requiredLengthM": 24, "requiredAreaM2": 72 }
    ]
  },
  "result": {
    "vehicleResults":    [ { "vehicleId": "V1", "requiredSpaceM2": 4.0, … } ],
    "clusterResults":    [ { "clusterId": 1, "totalSpaceM2": 14.2, … } ],
    "totalSpaceM2":      27.4,
    "peakByPeriod":      [ { "period": "0:00 - 6:00", "space": 0 }, … ],
    "serviceLevelCurve": [ { "serviceLevel": 0.5, "space": 8.1 }, … ]
  },
  "meta": {
    "numSimulations": 2500,
    "inputCounts":    { "F1": 362, "F10": 5 },
    "durationMs":     312
  }
}

summary is the recommended consumer field — lengths and areas are clearly labeled. The result block preserves the raw engine output for callers that need it. Note: the field names totalSpaceM2 and requiredSpaceM2 inside result are legacy — they hold length in meters, not area. Multiply by summary.loadingBayWidthM (3) for actual m².

Errors:

  • 400 — invalid input, with { "error": "…" } describing what was wrong.
  • 500 — internal error (should not happen; file a bug).

Example

curl -X POST https://your-host/api/v1/simulate \
  -H 'Content-Type: application/json' \
  -d '{ "functionBvoM2": { "F1": 32580, "F2": 3000 } }'

Notes on IDs

  • Vehicles: V1 (fiets/cargobike) … V6 (service bestelwagen) — see /api/v1/model/vehicles.
  • Functions: F1 (woningen) … F12 (kantoor groot) — see /api/v1/model/functions.
  • Distributions: D1 (afval bedrijven) … D15 (verhuizingen) — see /api/v1/model/distributions.
  • Cluster IDs are integers ≥ 1 chosen by the caller. Vehicles sharing a cluster share physical space; each cluster has its own service level.

Notes on the model

See CLAUDE.md and src/lib/simulation.ts for an in-depth description of the Monte Carlo model, including how arrival probabilities are computed and how percentile analysis converts per-iteration peaks into a required space.