Use the API¶

Every call except /login and /health needs a token. Sign in once, then send the token as a bearer header.

Sign in¶

API=https://localhost:8090
TOKEN=$(curl -sk -X POST $API/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"..."}' | jq -r .token)

A token lasts JWT_EXPIRATION (default 24h). Ask for another lifetime at sign-in with sessionDuration:

{"username": "alice", "password": "...", "sessionDuration": "36h"}

The server uses a self-signed certificate unless you configure one, hence -k in these examples.

Common calls¶

The full list, with every parameter and response, is in the REST API reference.

Deploy and inspect¶

curl -sk -X POST $API/api/v1/labs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"topologyContent":{"name":"srl01","topology":{
        "kinds":{"nokia_srlinux":{"type":"ixrd3","image":"ghcr.io/nokia/srlinux"}},
        "nodes":{"srl1":{"kind":"nokia_srlinux"},"srl2":{"kind":"nokia_srlinux"}},
        "links":[{"endpoints":["srl1:e1-1","srl2:e1-1"]}]}}}'

curl -sk -H "Authorization: Bearer $TOKEN" $API/api/v1/labs/srl01

Capture packets¶

Stream a capture to Wireshark on your machine:

curl -sk -N -H "Authorization: Bearer $TOKEN" \
  "$API/api/v1/labs/srl01/capture/stream?target=srl1:e1-1" | wireshark -k -i -

Repeat target to capture several interfaces into one stream. GET /api/v1/labs/{lab}/capture/interfaces lists what can be captured.

Follow events¶

/api/v1/events streams container and interface events as NDJSON, one object per line:

curl -sk -N -H "Authorization: Bearer $TOKEN" "$API/api/v1/events?initialState=true"

Add interfaceStats=true for interface counters.

Check what a server supports¶

GET /health needs no token. Its features list names optional capabilities, so clients can hide what an older server or another runtime does not offer:

curl -sk $API/health | jq .features

Explore interactively¶

A running server documents itself:

https://<host>:8090/swagger/index.html   # Swagger UI, try calls in the browser
https://<host>:8090/redoc                # ReDoc

Flashpost collection¶

Flashpost is a REST client inside VS Code. The repository ships a ready-made collection for every endpoint in example/flashpost. Import it and set its variables: