edgeware cloud service

Download as PDF

1 Introduction

1.1 Commercial Notice

Important note: Some of the features described in this release note may not be covered by your current licenses. Please contact Edgeware for further information.

1.2 Contact

For technical support, please contact Edgeware via the Support Portal.

1.3 History

Issue:A1
Date: 2019-04-26
Changes: First version

2 API specification

2.1 Basic description

The Cloud Monitor API provides monitoring of the overall state of a distributed SW Origin setup by giving access to metrics aggregated from the installation’s multiple availability zones.

The API is based on JSON over HTTPS with all requests performed with HTTPS GET.

2.2 Using the API

The Cloud Monitor API is available as an HTTPS service. All requests are performed using HTTPS GET with /api/1/monitor/ as the base path for all requests. monitor-url will be provided along with the account details.

2.2.1 Query strings

2.2.1.1 Resource schema

To get an informative schema of the resources that are available through the API, request the base path appended with the query parameter schema:

curl <monitor-url>/api/1/monitor/?schema

The response will be a JSON schema describing the structure and the datatypes of the available resources:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "services": {
      "type": "object",
      "properties": {
        "repackaging": {
          "type": "object",
          "properties": {
            "egressRate": {
              "type": "array",
              "description": "The egress rate time series for ...
              "title": "Egress rate",
              "items": {
                "type": "object",
                "title": "Egress rate sub-intervals",
                "properties": {
                  "startTime": {
                    "type": "number",
                    "description": "The start time for this sub-interval...
                    "title": "Start time"
                  },
                  "duration": {
                    "type": "number",
                    "description": "The duration of this sub-interval.",
                    "title": "Duration"
                  },
                  "bitrate": {
                    "type": "number",
                    "description": "The egress rate for this sub-interval...
                    "title": "Bitrate"
                  }
                }
              ...

In this example we can see that requesting the resource path services/repackaging/egressRate will produce a list of sub-intervals where each interval contains startTime, duration and bitrate.

2.2.1.2 Time window specification

To specify the time interval over which to get monitoring data, a time window can be supplied as a query string by extending the URL with e.g. ?startTime=1551945061&stopTime=1551946660. The time specification is in UNIX Epoch time, i.e. seconds since Jan 1 1970.

If only one of startTime or stopTime is supplied, the response will contain all data points during 1 hour fromor until the specified time. If neither startTime nor stopTime is provided, data for the last 1 hour is returned.

For each resource that can be requested, a list of sub-intervals covering the time span from startTime to stopTime is returned as a list. The duration of each sub-interval is 60 seconds:

curl "<monitor-url>/api/1/monitor/services/repackaging/egressRate?startTime=1551945100&stopTime=1551945660"
[
  {
    "startTime": 1551945060,
    "duration": 60,
    "bitrate": 2448491569
  },
  {
    "startTime": 1551945120,
    "duration": 60,
    "bitrate": 3583554835
  },
  {
    "startTime": 1551945180,
    "duration": 60,
    "bitrate": 3710126744
  },
  {
  ...

If there is no data available for some period of time, the response may omit entries for that period.

2.2.2 Available resources

2.2.2.1 /api/1/monitor/services/liveIngest/ingressRate

The ingressRate resource describes the total ingress traffic amount that is consumed by the Live Ingest nodes in the SW Origin setup. The bitrate unit is bits per second.

The response is a list of data broken down to one-minute intervals with start and stop time according to the time window specification.

[
  {
    'startTime': 1551945120,
    'duration': 60,
    'bitrate': 1011871606
  },
  ...
]

2.2.2.2 /api/1/monitor/services/repackaging/egressRate

The egressRate resource describes the total amount of egress traffic that is produced by the Repackager nodes in the SW Origin setup. The bitrate unit is bits per second.

The response is a list of data broken down to one-minute intervals with start and stop time according to the time window specification .

[
  {
    'startTime': 1551945060,
    'duration': 60
    'bitrate': 3381039680
  },
  ...
]

2.2.2.3 /api/1/monitor/services/liveIngest/channels

To get the state of a particular channel in the SW Origin setup, query the path

/api/1/monitor/services/liveIngest/channels/<channelName>

This will return a list with the channel’s state for every minute in the requested time interval. For example, to get the status of Channel2:

curl "<monitor-url>/api/1/monitor/services/liveIngest/channels/Channel2?startTime=1551945000&stopTime=1551948660"
[
  {
    "startTime": 1551945000,
    "duration": 60,
    "hasLive": true,
    "isRunning": true
  },
  {
    "startTime": 1551945060,
    "duration": 60,
    "hasLive": true,
    "isRunning": true
  },
  {
    "startTime": 1551945120,
    "duration": 60,
    "hasLive": true,
    "isRunning": true
  },
  ...

2.2.3 HTTPS response codes

The following response codes can potentially be returned by the server:

2.2.3.1 200 OK

The GET request was successfully completed.

2.2.3.2 400 Bad request

The syntax of the request is incorrect. The format of the request is not according to the specifications. Most likely some of the fields are missing. Please see the section of Available resourses to pinpoint the problem.

2.2.3.3 404 Not Found

The resource does not exist.

2.2.3.4 405 Method Not Allowed

The request method is not allowed. The HTTPS methods allowed is GET.

2.2.3.5 500 Internal Server Error

The server encountered an unexpected condition that prevents it from fulfilling the request.

2.2.3.6 502 Bad Gateway

One or more of the required backend services are unavailable.

2.2.3.7 503 Service Unavailable

The server is currently unable to handle the request due to a temporary overload or maintenance of the server.