3. List channels for a server

Request

The request URL for retrieving the list of channels for a server has the following form:

/channels/by-server/<server ID>/

The <server ID> has to be replaced by the UUID associated with the respective server. The request must use the GET method.

Response

The response is a JSON object with the channels and statusAvailable attributes as its members. The statusAvailable attribute is a boolean indicating whether the list of channels includes status information (true) or only configuration information (false). Status information is only available if the specified server is online. The channels attribute has an array as its value that contains an element for each channel. Each of these elements is an object with the following attributes:

Field nameInternal data typeJSON data typeDescription
channelDataIdUUIDstring internal ID for the channel
channelNamestringstring channel’s name
controlSystemNamestringstring human-readable name of the control-system support used for the channel
controlSystemTypestringstring internal identifier for the control-system support used for the channel
decimationLevelToRetentionPeriodmap of int to intobject with string attribute values decimation levels that exist for the channel and their respective retention periods (both specified in seconds)
enabledbooleanboolean true if the channel is enabled, false if it is disabled.
errorMessagestringstring error message for the channel. May be null.
optionsmap of string to stringobject with string attribute values control-system-specific configuration options that have been specified for the channel (the attribute name is the option name and the attribute value is the option value)
statestringstring channel’s current state. One of destroyed, disabled, disconnected, error, initializing, or ok. null if status information is not available.
totalSamplesDroppedlongstring number of samples that have been dropped for the channel (since the last reinitialization). null if status information is not available.
totalSamplesSkippedBacklongstring number of samples that were discarded because they skipped back in time (since the last reinitialization). null if status information is not available.
totalSamplesWrittenlongstring number of samples that have been written for the channel (since the last reinitialization). null if status information is not available.

If the list of channels is currently not available, HTTP error code 503 (service unavailable) is returned and the response body is invalid. If the specified server does not exist, HTTP error code 404 (not found) is returned and the response body is invalid.

Example

Request:

GET /admin/api/1.0/channels/by-server/7cf8f393-cd00-46ae-9343-53e9cb5793fd/

Response:

{
  "channels": [
    {
      "channelDataId": "ef126a63-375b-4f28-a1d1-17e8f42271a9",
      "channelName": "someChannel",
      "controlSystemName": "Channel Access",
      "controlSystemType": "channel_access",
      "decimationLevelToRetentionPeriod": {
        "0": "864000",
        "30": "31536000",
        "900": "0"
      },
      "enabled": true,
      "errorMessage": null,
      "options": {},
      "state": "OK",
      "totalSamplesDropped": "0",
      "totalSamplesSkippedBack": "1",
      "totalSamplesWritten": "42"
    },
    {
      "channelDataId": "0993955f-d16e-486d-ac3b-6a1841c0fd3f",
      "channelName": "someOtherChannel",
      "controlSystemName": "Channel Access",
      "controlSystemType": "channel_access",
      "decimationLevelToRetentionPeriod": {"0": "0"},
      "enabled": true,
      "errorMessage": "Invalid control-system option \"noSuchOption\".",
      "options": {
        "noSuchOption": "some value"
      },
      "state": "ERROR",
      "totalSamplesDropped": "0",
      "totalSamplesSkippedBack": "0",
      "totalSamplesWritten": "0"
    }
  ],
  statusAvailable: true
}