REST API of the Web Server (Plans for new API) (Outdated)

Note: This wiki page is outdated as the API overhaul pull request was merged on 25th September 2025. On this page, we collected plans for how that very overhaul to the API might be done (in terms of what endpoints we wanted/thought could be useful). The wiki page will be updated at some point to keep ideas we might want to implement in future updates.

The organisation of the API is based on the functionalities needed by different user roles: administrator, controller, driver, uploader, and monitor. The API end points are defined in the main function of the server.c file. Note that all APIs are called using HTTP POST methods, whose parameters may include data and files. All APIs return an HTTP response, e.g., OK or HTTP_BAD_REQUEST.

Administrator

Maintain overall control of a railway platform at all times.

• /admin/startup: Start up the digital railway control boards and initialises the railway components (e.g., points, signals, trains) to defaults.
  • No parameters.
  • No return value.
• /admin/shutdown: Release all grabbed trains and shuts down the digital railway control boards.
  • No parameters.
  • No return value.
• /admin/set-track-output: Set the power state of all track outputs.
  • Data parameters:
    • state, integer: 0 (off), 1 (stop), 2 (soft_stop), or 3 (go) for the requested power state of all track output.
  • No return value.
• /admin/set-verification-option: Set whether plugins will be verified upon upload.
  • Data parameters:
    • verification-option, Boolean: true (enable) or false (disable).
  • No return value.
• /admin/set-verification-url: Set the URL of the verification server to use for verification on upload.
  • Data parameters:
    • verification-url, string: The verification server URL.
  • No return value.
• /admin/release-train: Release a grabbed train.
  • Data parameters:
    • train, string: The train's name.
  • No return value.
• /admin/set-dcc-train-speed: Set the DCC speed step of a train.
  • Data parameters:
    • train, string: The train's name.
    • speed, integer: The requested DCC speed step between 0 and 126, inclusive.
    • track-output, string: The name of the digital railway control board to broadcast the requested DCC speed step.
  • No return value.

Controller

Select and control the track layout (points and signals) of a railway platform.

• /controller/release-route: Release a route.
  • Current: Sent a postrequest with requestdata schema {"route-id": <route-id>}
  • Parameter:
    • route-id, string: Route-ID
  • Reponse: Empty, Statuscode 200
• /controller/set-point: Set the aspect of a point.
  • Current: Sent a postrequest with requestdata schema {"point": <point-id>, "state" <"normal" | "reverse">}
  • Parameter:
    • point, string: Point-ID
    • state, string: normal or reverse
  • Response: Empty, Statuscode 200
• /controller/set-signal: Set the aspect of a signal.
  • Current: Sent a postrequest with requestdata schema {"signal": <signal-id>, "state": <"aspect_go" | "aspect_stop" | "aspect_caution" | "aspect_shunt"}
  • Parameter:
    • Signal, string: Signal ID
    • State, string: aspect_go or aspect_stop or aspect_caution or aspect_shunt (not every signal supports every state)
  • Response: Empty, Statuscode 200
• /controller/set-peripheral: Set the aspect of a peripheral.
  • Current: Sent a postrequest with schema {"verification-url": <verification-url>}
  • Parameter:
    • Verification-url, string: URL with verification file
  • Response: Empty, Statuscode 200
• /controller/get-interlocker: Get the name of the interlocker in use.
  • Current: Sent a empty postrequest
  • Response: single line String with interlocker
• /controller/set-interlocker: Set an interlocker to use.
  • Current: Sent a postrequest with schema {"interlocker": <interlocker>}
  • Parameter:
    • interlocker: string, just installed interlockers
  • Response: Single Line String with interlocker, Statuscode 200
• /controller/unset-interlocker: Unset an interlocker from use.
  • Current: Sent a postrequest with schema {"interlocker": <interlocker>}
  • Response: Empty, Statuscode 200

Driver

Select and drive a train that is on a railway platform.

• /driver/grab-train: Grab a train.
  • Data parameters:
    • train, string: The train's name.
    • engine, string: The name of the train engine behaviour to use.
  • Return values:
    • session-id, integer: Number that identifies the server's current session.
    • grab-id, integer: Number that identifies the train driver.
• /driver/release-train: Release a grabbed train.
• /driver/request-route: Request a route for a grabbed train from a source to a destination signal.
• /driver/request-route-id: Request a specific route ID for a grabbed train.
• /driver/direction: Get a train's required physical driving direction for a given route.
• /driver/drive-route: Drive a grabbed train along its granted route in automatic or manual mode.
• /driver/set-dcc-train-speed: Set the DCC speed step of a grabbed train.
  • Data parameters:
    • session-id, integer: Number that identifies the server's current session.
    • grab-id, integer: Number that identifies the train driver.
    • speed, integer: The requested DCC speed step between 0 and 126, inclusive.
    • track-output, string: The name of the digital railway control board to broadcast the requested DCC speed step.
  • No return value.
• /driver/set-calibrated-train-speed: Set the calibrated speed step of a grabbed train.
• /driver/set-train-emergency-stop: Perform an emergency stop for a grabbed train.
• /driver/set-train-peripheral: Set a peripheral of a grabbed train.

Upload

Upload, process, and manage external files.

• /upload/engine: Upload a train engine.
• /upload/refresh-engines: Get a list of available train engines.
• /upload/remove-engine: Delete an uploaded train engine.
• /upload/interlocker: Upload an interlocker.
  • Files parameters:
    • file: The BahnDSL (*.bahn) file to upload as file data.
  • Return values:
    • status-code, string: The status as a mnemonic.
    • status-text, string: Human readable description of the status code.
• /upload/refresh-interlockers: Get a list of available interlockers.
• /upload/remove-interlocker: Delete an uploaded interlocker.

Monitor

Provide real-time state information of a railway platform.

• /monitor/trains: Get a list of trains.

  • Current: Returns a multiline string. Each line contains information on one train each; in the format: <train name> - grabbed: <"yes"|"no">
  • Proposed: Set of "train" objects. Each train object contains:
    • grabbed: boolean - whether train is grabbed or not
    • name: string - name of the train
    • routeID: string - if any route is granted to this train, its ID is given here. If no route is granted to this train, empty str or "none" (tbd.)

• /monitor/train-state: Get the state of a train.

  • Current: String with the following information:
    • grabbed: <"yes"|"no">
    • - on segment: <"no"|seg_string>
      • seg_string: segmentID [, segmentID]*
    • - on block: <"no"|block_id>
    • - orientation: <"left"|"right">
    • - speed step: <number>
    • - detected speed: <number> km/h
    • - direction: <"forwards"|"backwards">
  • Proposed: "train"(-info) object with the following information:
    • grabbed: boolean
    • on_segments: set(? tbd) of strings
    • on_block: string
    • orientation: string ("left"|"right")
    • direction: string ("forwards"|"backwards")
    • speed_step: number
    • detected_speed_kmh: number
    • route_id: string (see doc. for monitor/trains)

• /monitor/train-peripherals: Get a list of peripherals of a train.

  • Current: Multiline string, with one peripheral per line. Each line has format: <peripheral-id> - state: <"on"|"off">
  • Proposed: List/Set (?) off "peripheral" objects. Each has info/fields:
    • id: string
    • is_on: boolean

• /monitor/track-outputs: Get a list of track outputs.

  • Current: Multiline string, with one track output per line. Each line has the form <track-output-id> - state: <state> where state can be one of "off", "stop", "soft stop", "go", "go + ignore watchdog", "prog", "prog busy", "busy", "query".
  • Proposed: List/Set (?) of "track-output" objects. Each has info/fields:
    • id: string
    • state: string

• /monitor/points: Get a list of points.

  • Current: Multiline string, with information on one point per line. Each line has the format: <point-id> - state: <"unknown"|"normal"|"reverse"> <"(target state reached)"|"(target state not reached)">
  • Proposed: List/Set (?) of "point" objects. Each has info/fields:
    • id: string
    • target_state: string
    • target_state_reached: boolean
  • Proposed maybe: Add info...
    • possible_states: list of strings (to be discussed, as this can be retrieved with monitor/point-aspects)
    • which track segment ID this point is related to
    • in which "direction" it's stem points (not sure how one would do this for double-slip switches, and how this is to be integrated in libbidib. So, not very likely. This would help when building an automatic visualization of the tracks, which is prob. better done from bahnDSL directly?)

• /monitor/signals: Get a list of signals.

  • Current: Multiline string, with information on one signal per line. Each line has the format: <signal-id> - state: <"unknown"|aspect> where aspect is a string representing the aspect of the signal, whose possible values depend on the specific signal (defined in the configuration files; as of 2023-09-19 in "bidib_track_config.yml" -> e.g. "aspect_caution", "aspect_go", "aspect_stop")
  • Proposed: List/Set (?) of "signal" objects. Each has info/fields:
    • id: string
    • state: string
  • Proposed maybe:
    • orientation (direction?): string. indicates in what driving direction this signal is "relevant".
    • possible_states: list of strings (to be discussed, as this can be retrieved with monitor/signal-aspects)
    • signal_type: string with keyword/name of the type of signal; e.g., entry, exit, distant, shunt, platformlight
    • distant_indicated_stop_signals: if the signal is a "distant"-type signal, list of signal-ids of the signals possibly indicated by it (it's "home" and "starting" signals (https://vicsig.net/index.php?page=infrastructure&section=signalling) it can "indicate"). In quite a few cases, this will only be one signal, but not always. If it's not a distant signal, empty list.
    • composit_signal_id: if signal is part of a composite (i.e., on one "mast" as another), give the string id of the composite form. E.g., signal46a would have "signal46" here.
    • related_overlap_segment_id: string. (unlikely), (for entry, exit, and shunt signals, otherwise empty string or "none"). ID of the track segment that is the overlap segment at this signal; meaning that if a train travels in the direction/orientation of this signal, and reaches this overlap segment, it has overrun the signal. Potential issue: Would then also want to know the segment before the signal, i.e. where it is okay to stop before it. This could also be conveyed in a tuple: segment-id-1, signal-id, segment-id-2 -> indicates that segment-id-2 is overlap after this signal.

• /monitor/point-aspects: Get the aspects of a point.

  • Current: Comma/Space-separated string with the potential aspects of a point, in format: <point-aspect-str> (, <point-aspect-str>)*

• /monitor/signal-aspects: Get the aspects of a signal.

  • Current: Comma/Space-separated string with the potential aspects of a signal, in format: <signal-aspect-str> (, <signal-aspect-str>)*

• /monitor/segments: Get a list of segments.

  • Current: Multiline string, with information on one segment per line. Each line has format: <segment-id> - occupied: <"yes trains: " <train-id|"unknown"> (", "<train-id|"unknown">)* |"no">
  • Proposed: List/Set (?) of "segment" objects. Each has info/fields:
    • id: string
    • occupied: boolean
    • occupied_by: list of strings; name of occupiers, might be "unknown" if no name known. Empty if not occupied
  • Proposed maybe (could also be a new endpoint where more detailed info on a single segment can be queried):
    • is_overlap: boolean
    • is_main: boolean
    • is_reversable: boolean
    • related_block: string
    • SOMETHING FOR A "BLOCK" ENDPOINT: signals: list of URIs (or objects that contain URIs + ID) for signals "on" this block. The URIs point to the monitor/signal endpoint with the id of this signal, such that more info can easily be acquired.

• /monitor/reversers: Get a list of track loop reversers.

  • Current: multiline string, with information on one reverser per line. Each line has the format: <reverser-id> - state <"unknown"|"on"|"off">
  • List / Set of "reversers" objects, each has info/fields:
    • reverser-id: string
    • state: string

• /monitor/peripherals: Get a list of peripherals.

  • Current: multline string with information on one peripheral per line. Each line has the format: <peripheral-id> - <state-id>: <state-value>
  • List / Set of "peripherals" objects, each has info/fields:
    • peripheral-id: string
    • state-id: string
    • state-value: number

• /monitor/verification-option: Get whether plugins will be verified upon upload.

  • Current: singleline String with returns if the verifiaction is enabled, format: verification-enabled: <"true"|"false">
  • verification-enabled: boolean

• /monitor/verification-url: Get the URL to the verification server.

  • Current: singleline String which returns the verification url, format: verification-url: <"null"|url>
  • verification-url: string

• /monitor/granted-routes: Get a list of granted routes.

  • Current: multiline String with information on one granted route per line. Each line has the format: route id: <route-id> train: <train>
  • List / Set of "granted routes" objects, each has info/fields:
    • route-id: number
    • train: string

• /monitor/route: Get the details of a route.

  • Current: multiline string with information about a custom route, where the routeid is sent via form-data (UNCLEAR)
  • Format:
    route id: <route-id> Number
    source signal: <signal-id> String
    destination signal: <signal-id> String
    orientation: <"clockwise"|"anticlockwise"> String
    length: <length> Number
    path: <segment-id1>, <segment-id2>Multiple Strings
    sections: <section-id> String
    points: <point-id1>, <point-id2> Multiple Strings
    confliction route ids: <route-id1>, <route-id2> Multiple Numbers
    status:
granted confliction route ids: <"none"|route-id> List of Numbers
    route clear: <"yes"|"no"> String
    granted train: <"none"|train> String

• /monitor/debug: Get debugging information related to the dynamic containers.

• /monitor/debug_extra: Get extra debugging information related to the dynamic containers.