Newansage v0.4.0 is out
ansage
Reference / HTTP API

HTTP API

The read-only JSON endpoints and the Server-Sent Events stream at metrics_listen.

View as Markdown Edit on GitHub

With metrics_listen = "127.0.0.1:9179", ansage serves Prometheus metrics and a read-only JSON copy of the control socket's answers. Nothing that changes state is reachable over HTTP.

PathQuerySame as
/a one-line pointer to the other paths
/metricsany (ignored)see Metrics
/api/summaryansage show summary --json
/api/peerspeer=ID|ADDRESS|ADDRESS:PORT (optional)ansage show peers --json, show peer N --json
/api/ribprefix=P, or family=ipv4|ipv6 and limit=N; out=NEIGHBOR for what a neighbor was sentansage show rib ... --json
/api/fibansage show fib --json
/api/eventsServer-Sent Events, below

Behavior

  • GET and HEAD only; other methods get 405.
  • Unknown query parameters or bad values get 400 with {"error": "..."}, unknown paths 404.
  • One request per connection (Connection: close).
  • At most 8 requests at a time, and 4 open event streams; more are turned away (503 for streams).
  • The request head must arrive within 5 s and be at most 8 KiB.
  • Times are unix milliseconds (since, now, started).

Examples

curl -s localhost:9179/api/summary | jq
curl -s 'localhost:9179/api/peers?peer=10.0.0.1' | jq '.[0].status.state'
curl -s 'localhost:9179/api/rib?prefix=198.51.100.0/24' | jq
curl -s 'localhost:9179/api/rib?family=ipv6&limit=10' | jq
/api/summary
{
  "version": "0.2.0",
  "asn": 64500,
  "router_id": "203.0.113.1",
  "started": 1794070242614,
  "now": 1794070263073,
  "announce": ["2001:db8:1::/48", "192.0.2.0/24"],
  "drained": null,
  "rib": { "prefixes_ipv4": 2, "prefixes_ipv6": 2, "attr_sets": 3 },
  "peers": [
    {
      "id": 1,
      "address": "10.0.0.1:179",
      "asn": 64501,
      "description": "r1 (FRR)",
      "state": "Established",
      "since": 1794070242615,
      "received_ipv4": 1,
      "received_ipv6": 1,
      "advertised_ipv4": 1,
      "advertised_ipv6": 1
    }
  ]
}

drained is the time the drain started, or null. Each entry of /api/peers has neighbor (the config), status (state, timers, last_error, last_down, the negotiated session), counters and rib.

Live events

/api/events is a Server-Sent Events stream, for a dashboard that updates without polling:

EventWhenData
summaryat once, every 5 s and when the neighbors change (reload)the /api/summary JSON
peerwhen a neighbor's state, timers or last error changethat neighbor's /api/peers entry
errorwhen an answer fails{"error": "...", "event": "summary"}
curl -N localhost:9179/api/events
event: summary
data: {"announce":["2001:db8:1::/48","192.0.2.0/24"],"asn":64500,"drained":null,...}

event: peer
data: {"counters":{...},"neighbor":{...},"rib":{...},"status":{"state":"Established",...}}

In a browser (ansage sends no CORS headers, so serve the dashboard and /api/ from the same origin, e.g. through a reverse proxy):

const events = new EventSource("/api/events");
events.addEventListener("peer", (e) => {
	const peer = JSON.parse(e.data);
	console.log(peer.neighbor.address, peer.status.state);
});

Esc to close