API Overview

This documentation is going to assume that you have the API setup somewhere. And that the base URL is going to be http://localhost:8002 .

For local development you can use the Swagger Documentation link.

REST Endpoints

These endpoints can all be accessed directly from the browser, and only allow for GET requests. This is only going to be a subset of the endpoints, for more details descriptions for to the Swagger Documentation, on any install this can be retrieved by going to /docs.

Ping

This endpoint can be used to determine if the API is responding to requests.

$ curl http://localhost:8002/ping
{"ping":"live"}

Config

This endpoint provides you with details on the current setup. It also lists some important endpoints that can be used to get further details.

$ curl http://localhost:8002/config

{
  "api_format": "msgpack",
  "app_version": "0.19.1",
  "project_name": "SDP Signal Metrics API",
  "start_time": "2023-11-01T09:24:51.743138+00:00",
  "uptime": 10771.529922008514,
  "paths": {
    "websocket": "/consumer",
    "subarrays": "/stats/subarrays",
    "processing_blocks": "/stats/processing_block/blocks",
    "spead2_scans": "/stats/spead2/scans",
    "spectogram_full_image_path": "/spectograms/full_image_pb/latest",
    "spectogram_thumbnail_path": "/spectograms/thumbnail_pb/latest",
    "lag_plot_full_image_path": "/lag_plots/full_image",
    "lag_plot_thumbnail_path": "/lag_plots/thumbnail",
    "log_url": "/log-dashboards"
  },
  "topics": {
    "phase_and_amplitude": "metrics-phase_and_amplitude-<subarray>",
    "rfi": "metrics-rfi-<subarray>",
    "spectrum": "metrics-spectrum-<subarray>"
  },
  "waterfall_plots": {
    "thumbnail_width": 500,
    "thumbnail_max_height": 164
  }
}

From the above you can see the expected data format of the websocket data in api_format. As well as what the links are to the various endpoints. The topics key also lists the topics that are available in the websocket.

Dashboard and Monitoring links

This endpoint will give you links to where you can get the logs from Kibana and the namespace monitoring in Grafana.

$ curl http://localhost:8002/log-dashboards/01

{
  "kibana": "https://k8s.stfc.skao.int/kibana/app/discover#/?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-15m,to:now))&_a=(columns:!(kubernetes.namespace,kubernetes.pod.name,kubernetes.container.name,message),filters:!(),grid:(columns:(kubernetes.namespace:(width:(width:120)),kubernetes.pod.name:(width:(width:150)),kubernetes.container.name:(width:(width:120)))),index:cbb05bec-ed81-45f8-b11a-eab26a3df6b1,interval:auto,query:(language:kuery,query:'kubernetes.namespace: \"default\" or kubernetes.namespace: \"default-p\"'),sort:!(!('@timestamp',desc)))",
  "grafana": {
    "sdp": "https://k8s.stfc.skao.int/grafana/d/dad0e09f-32f5-4181-b273-c7a1017221ff/kubernetes-resource-monitoring-dashboard?orgId=1&refresh=5s&var-namespace=default",
    "pipeline": "https://k8s.stfc.skao.int/grafana/d/dad0e09f-32f5-4181-b273-c7a1017221ff/kubernetes-resource-monitoring-dashboard?orgId=1&refresh=5s&var-namespace=default-p"
  }
}

Known Execution Blocks

This endpoint will provide you with a list of the known execution blocks as well as which is the current latest.

$ curl http://localhost:8002/stats/execution_blocks

{
  "all": [
    {
      "id": "eb-fake-test-20231101-90471",
      "processing_blocks": [
        "pb-fake-test-20231101-80848"
      ]
    }
  ],
  "latest": "eb-fake-test-20231101-90471",
  "last_update": "2023-11-01T13:20:08.949592+00:00"
}

Known Subarrays

This endpoint will provide you with a list of the known Subarrays as well as which is the current latest.

$ curl http://localhost:8002/stats/subarrays

{
  "all": [
    {
      "id": "01",
      "processing_blocks": [
        "pb-fake-test-20231101-80848"
      ]
    }
  ],
  "latest": "01",
  "last_update": "2023-11-01T13:20:08.950024+00:00"
}

Known Processing Block IDs

This endpoint will provide you with a list of the known Processing Block IDs as well as which is the current latest.

$ curl http://localhost:8002/stats/processing_block/blocks

[
  "pb-fake-test-20231101-80848"
]

Known Scan IDs

This endpoint will provide you with a list of the known Scan IDs as well as which is the current latest.

$ curl http://localhost:8002/stats/spead2/scans

[
  1
]

WebSocket Endpoints

These endpoints should be connected to using a websocket to get data. The format of the data in any websocket call is dependent on the data type that is in the Config endpoint.

The API can currently support json and msgpack formats. Regardless of which format is choosing the output of the first message is always the same, an object with a single key/value pair. That looks like {"status": "connected"}.

Once that is received the websocket will start sending data as is available.

The topics that can be accessed can be found in the Config endpoint, with what is required at the end. For example if you want to get the Spectrum data from subarray 01 you would connect to the topic metrics-spectrum-01.

The URL to get to a websocket is /consumer/<topic>.