Red5 Pro Stream Manager REST API (v2.0)

With Red5 Pro Server Release Version 2.1.0, there is an udpated Stream Manager API.

If you are running Stream Manager with Red5 Pro Server Version 2.0.0 or earlier, then please refer to > Red5 Pro Stream Manager API v1.0 for the correct API calls.

Red5 Pro Stream Manager is a streaming architecture management and information service which helps automate the process of creating and deleting Red5 Pro instances. Stream Manager also coordinates between broadcasters and subscribers to help them find the correct servers for their broadcast and subscribe action, respectively.

Stream Manager also provides stream statistics over simple HTTP-based REST API calls, once publishing has started.


The following documents also pertain to autoscaling and the Red5 Pro Stream Manager:

> Autoscaling Streams with Red5 Pro

> Red5 Pro Stream Manager User Guide


Getting Started

Red5 Pro Stream Manager REST API calls can be executed using any standard REST client.

For this section we will be using Google Chrome Add-On: Postman REST client. You need to have the latest Chrome Browser installed on your computer to install the Add-On.


Given below are examples on using POST, GET and DELETE type REST operations using the Postman REST client. These are the three type of operations that you will come across while using the Stream Manager REST API.

Note: In examples, the URL pattern of {host} will refer to the Stream Manager IP/hostname and {port} will be 5080, the default port for Red5.

Making POST API Calls

To make a POST REST call using the Postman REST client:

  1. Enter your URL in the URL text field
  2. Select POST from methods list on the left-hand side of URL text field
  3. If you have any accompanying data:
    • Select Body tab and select raw option
    • Select JSON (application/json) in the drop down selector next to the raw option
    • Paste the desired JSON data into the text area exposed on selecting raw
  4. Click Send to execute your API call

REST API POST Exmaple


Making GET API Calls

To make a GET REST call using the Postman REST client:

  1. Enter your URL in the URL text field
  2. Select GET from methods list on the left-hand side of URL text field
  3. Click Send to execute your API call

REST API GET Exmaple


Making DELETE API Calls

To make a DELETE REST call using the Postman REST client:

  • Enter your URL in the URL text field
  • Select DELETE from methods list on the left-hand side of URL text field
  • Click Send to execute your api call

REST API DELETE Exmaple


REST API for Groups

Create Group

Description

Create a new node group.

REQUEST

  • URI : http://{host}:{port}/streammanager/api/2.0/admin/nodegroup?accessToken=<accessToken>
  • Method: POST
  • Data: JSON
      {
          "regions": [
              "<region-code>"
          ],
          "launchConfig": "<launch-config-name>",
          "scalePolicy": "<scale-policy-name>"
      }
    

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 201
  • Data:
      {
        "id": <autogen-group-id>,
        "name": "<autogen-group-name>",
        "originConnections": <min-origin-connections>,
        "regions": [
          "<region-code>"
        ],
        "launchConfig": "<launch-config-name>",
        "scalePolicy": "<scale-policy-name>",
        "timestamp": <timestamp>
      }
    

Example

REQUEST

  • URI: http://{host}:5080/streammanager/api/2.0/admin/nodegroup?accessToken=xyz123
  • Method: POST
  • Data : JSON
      {
          "regions": [
              "us-central1",
              "us-east1"
          ],
          "launchConfig": "default",
          "scalePolicy": "default"
      }
    

RESPONSE

  • Success: HTTP CODE 201
  • Data:
      {
        "id": 2,
        "name": "group-d2f6aade-c6eb-4b92-b056-3f3a9f99b96f",
        "originConnections": 0,
        "regions": [
          "us-central1",
          "us-east1"
        ],
        "launchConfig": "default",
        "scalePolicy": "default",
        "timestamp": 1452595891000
      }
    

regions

The geographical regions where you would like the nodes to be created. Stream Manager usually lets the Autoscaler use this list in a round-robin style. You can find a list of available Google Cloud regions here or a list of available AWS regions here.

originConnections

An attribute reserved for future use. Currently this is always set to zero, whena new group is created.

launchConfig

Name of the launch configuration to be used for launching each new instance in the nodegroup. Usually this implies the consistent machine configuration for a group. A launch configuration defines your machine type, max connections, etc. for each instance type (origin and edge).

scalePolicy

Name of the scale policy to be used by Autoscaler to launch new edges when load conditions occur. A scale policy defines details such as min-max edges allowed, instances warm-up time, cooldown period, etc.


List Groups

Description

List all available groups in the system.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      [
      {
        "id": <autogen-group-id>,
        "name": "<autogen-group-name>"
        "originConnections": <min-origin-connections>,
        "regions": [
          "<compute-region-code>"
        ],
        "launchConfig": "<launch-config-name>",
        "scalePolicy": "<scale-policy-name>",
        "timestamp": <timestamp>
      }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      [
        {
          "id": 3,
          "name": "group-e658a196-cb39-411a-86c1-d1e618222100"
          "originConnections": 0,
          "regions": [
            "us-central1-a",
            "us-central1-f"
          ],
          "launchConfig": "default",
          "scalePolicy": "default",
          "timestamp": null
        },
        {
          "id": 4,
          "name": "group-51921df1-d68e-4fee-8332-6dbdf7102e47",
          "originConnections": 0,
          "regions": [
            "us-central1-a",
            "us-central1-f"
          ],
          "launchConfig": "default",
          "scalePolicy": "default",
          "timestamp": null
        }
      ]
    

List Group Nodes

Description

List all nodes in a group and their status. The different statuses for a node are:

  • pending (stream manager has contacted the cloud service to start an instance)
  • running (instance has been launched, and services are starting up)
  • inservice (node is active and available for streaming)
  • terminating (node is being deactivated)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/{groupName}/node?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • DATA:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      [
       {
          "identifier": "<node-identifier>",
          "role": "<role>",
          "availabilityZone": "<availability-zone-code>",
          "address": "<host>",
          "state": "<node-state>",
          "launchConfig": "<launch-config-name>",
          "capacity": <connection-capacity>
        }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/group-8bcc96ed-b7e5-4044-b797-1bc93d5f0be4/node?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      [
        {
          "identifier": "node-us-central1-a-1452586832022",
          "role": "origin",
          "availabilityZone": "us-central1-a",
          "address": "104.197.131.87",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 1500
        },
        {
          "identifier": "node-us-central1-a-1452587484090",
          "role": "edge",
          "availabilityZone": "us-central1-a",
          "address": "104.197.138.228",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 500
        }
        ]
    

List Group Origins

Description

List all origin nodes in a group.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/{groupName}/node/origin?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • DATA:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • DATA:
      [
       {
          "identifier": "<node-identifier>",
          "role": "<role>",
          "availabilityZone": "<availability-zone-code",
          "address": "<host>",
          "state": "<node-state>",
          "launchConfig": "<launch-config-name>",
          "capacity": <connection-capacity>
        }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/group-8bcc96ed-b7e5-4044-b797-1bc93d5f0be4/node/origin?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
      [
        {
          "identifier": "node-us-central1-a-1452586832022",
          "role": "origin",
          "availabilityZone": "us-central1-a",
          "address": "104.197.131.87",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 1500
        }
      ]
    

List Group Edges

Description

List all edge nodes in a group.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/{groupName}/node/edge?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      [
       {
          "identifier": "<node-identifier>",
          "role": "<role>",
          "availabilityZone": "<availability-zone-code",
          "address": "<host>",
          "state": "<node-state>",
          "launchConfig": "<launch-config-name>",
          "capacity": <connection-capacity>
        }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/group-8bcc96ed-b7e5-4044-b797-1bc93d5f0be4/node/edge?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      [
        {
          "identifier": "node-us-central1-a-1452587484090",
          "role": "edge",
          "availabilityZone": "us-central1-a",
          "address": "104.197.138.228",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 500
        },
        {
          "identifier": "node-us-central1-f-1452587643929",
          "role": "edge",
          "availabilityZone": "us-central1-f",
          "address": "104.197.234.171",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 500
        }
      ]
    

Read Group

Description

Reads a node group.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/<groupName>?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "id": <autogen-group-id>,
        "originConnections": 0,
        "name": "<autogen-group-name>",
        "region": [
          "<region-code>"
        ],
        "launchConfig": "<launch-config-name>",
        "scalePolicy": "<scale-policy-name>",
        "timestamp": <timestamp>
      }
    

Example

REQUEST

  • URI: http://{host}:5080/streammanager/api/2.0/admin/nodegroup/group-d2f6aade-c6eb-4b92-b056-3f3a9f99b96f?accessToken=xyz123
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "id": 2,
        "name": "group-d2f6aade-c6eb-4b92-b056-3f3a9f99b96f",
        "originConnections": 0,
        "regions": [
          "us-central1",
          "us-east1"
        ],
        "launchConfig": "default",
        "scalePolicy": "default",
        "timestamp": 1452595891000
      }
    

Delete Group

Description

Deletes a node group. If the group has no nodes in it then it is deleted right away, otherwise all the nodes of the group are deleted in the background separately, and then the group itself is deleted once it is empty.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/<groupName>?accessToken=<accessToken>
  • Method: DELETE

RESPONSE

  • FAILURE: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "id": <autogen-group-id>,
        "name": "<autogen-group-name>",
        "originConnections": 0,
        "regions": [
          "<compute-region-code>"
        ],
        "launchConfig": "<launch-config-name>",
        "scalePolicy": "<scale-policy-name>",
        "timestamp": <timestamp>
      }
    

Example

REQUEST

  • URI: http://{host}:5080/streammanager/api/2.0/admin/nodegroup/group-d2f6aade-c6eb-4b92-b056-3f3a9f99b96f?accessToken=xyz123
  • Method: DELETE

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "id": 2,
        "name": "group-d2f6aade-c6eb-4b92-b056-3f3a9f99b96f",
        "originConnections": 0,
        "regions": [
          "us-central1",
          "us-central1"
        ],
        "launchConfig": "default",
        "scalePolicy": "default",
        "timestamp": 1452595891000
      }
    

Launch New Origin

Description

Launches a new origin for a node group. Launching a node on a Cloud Platform is a complex asynchronous process. The REST gateway will provide you a response as soon as it knows that the cloud platform has acknowledged the request.

The maximum number of origins allowed in a nodegroup is defined through the scale policy file. Additional origins cannot be launched in a group after an edge has been launched in it.

The actual instance boot up may take up to two minutes, dependingo on the environment.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/{groupName}/node/origin?accessToken=<accessToken>
  • Method: POST

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 201
  • Data:
      {
        "id": <auto-gen-id>,
        "identifier": "<node-identifier>",
        "availabilityZone": "<availability-zone-code>",
        "role": "<role>",
        "group": "<group-identifier>",
        "requestTime": <timestamp>
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/group-51921df1-d68e-4fee-8332-6dbdf7102e47/node/origin?accessToken=xyz123
  • Method: POST

RESPONSE

  • Success: HTTP CODE 201
  • Data:
      {
        "id": 6,
        "identifier": "node-us-central1-a-1452600712264",
        "availabilityZone": "us-central1-a",
        "role": "origin",
        "group": "group-51921df1-d68e-4fee-8332-6dbdf7102e47",
        "requestTime": 1452600723615
      }
    

Read Group Stats

Description

Displays the load statistics for this node group. Edge statistics is gathered via the reports received through origin, whereas the origin statistics are directly evaluated by streammanager.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/{groupName}/stats?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • DATA:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "totalConnections": <total-group-connections>,
        "targetTypeLoadSummary": [
          {
            "type": "<role>",
            "totalNodeCount": <total-node-count>,
            "totalActiveNodeCount": <total-active-nodes>,
            "netConnectionCapacity": <total-available-capacity>,
            "netConnectionLoad": <total-connection-load>
          }
        ]
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/nodegroup/group-8bcc96ed-b7e5-4044-b797-1bc93d5f0be4/stats?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "totalConnections": 0,
        "targetTypeLoadSummary": [
          {
            "type": "origin",
            "totalNodeCount": 1,
            "totalActiveNodeCount": 1,
            "netConnectionCapacity": 5,
            "netConnectionLoad": 0
          },
          {
            "type": "edge",
            "totalNodeCount": 1,
            "totalActiveNodeCount": 0,
            "netConnectionCapacity": 30,
            "netConnectionLoad": 0
          }
        ]
      }
    

REST API for Nodes

Read Node

Description

Reads a node by its host address.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/node/<host-address>?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
       {
          "identifier": "<node-identifier>",
          "role": "<role>",
          "availabilityZone": "<availability-zone-code",
          "address": "<host>",
          "state": "<node-state>",
          "launchConfig": "<launch-config-name>",
          "capacity": <connection-capacity>,
          "group": <group-identifier>
        }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/node/104.197.138.228?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
          "identifier": "node-us-central1-a-1452586832022",
          "role": "origin",
          "availabilityZone": "us-central1-a",
          "address": "104.197.131.87",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 1500,
          "group": "group-8bcc96ed-b7e5-4044-b797-1bc93d5f0be4"
        }
    

Terminate Node

Description

Terminates a node by its host address. This requires that the node is not in a state other than the INSERVICE state.If a node is already in terminating state or is a newly launched node it cannot be terminated till it becomes active (attains the INSERVICE state).

Optionally you can force delete a node using the boolean query parameter force if it is stuck in a transitioning state for long and you ar eunable to terminate it normally.The value forthe parameterforce can be true or false.This will remove the node entry from database and streammanager will delete it from cloud after sometime.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/node/<host-address>?accessToken=<accessToken> OR http://{host}:{port}/streammanager/api/2.0/admin/node/<host-address>?accessToken=<accessToken>&force=true
  • Method: DELETE

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
       {
          "identifier": "<node-identifier>",
          "role": "<role>",
          "availabilityZone": "<availability-zone-code>",
          "address": "<host>",
          "state": "<node-state>",
          "launchConfig": "<launch-config-name>",
          "capacity": <connection-capacity>,
          "group": <group-identifier>
        }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/node/104.197.228.198?accessToken=xyz123
  • Method: DELETE

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
          "identifier": "node-us-central1-a-1452586832022",
          "role": "origin",
          "availabilityZone": "us-central1-a",
          "address": "104.197.228.198",
          "state": "inservice",
          "launchConfig": "default",
          "capacity": 1500,
          "group": "group-8bcc96ed-b7e5-4044-b797-1bc93d5f0be4"
      }
    

Read Node Stats

Description

Displays the load statistics for a single node (edge or origin).

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/node/{host}/stats?accessToken=<accessToken>
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • DATA:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "totalConnections": <total-connection-count>,
        "parents": [
          "<parent-host-1>",
          "<parent-host-N>"
        ],
        "lastTrafficTime": <last-traffic-time>,
        "lastPing": <last-ping-time>,
        "group": "<group-identifier>",
        "identifier": "<node-identifier>",
        "role": "<role>",
        "availabilityZone": "<availability-zone-code>",
        "address": "<host>",
        "state": "<node-state>",
        "launchConfig": "<launch-configuration-name>",
        "capacity": <connection-capacity>
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/1.0/admin/node/54.152.171.193/stats?accessToken=xyz123
  • Method: GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "totalConnections": 0,
        "parents": [
          "54.92.190.62"
        ],
        "lastTrafficTime": 0,
        "lastPing": 1483534238634,
        "group": "group-7fd29762-58f9-4177-a503-04d7f5e1aa49",
        "identifier": "node-us-east-1a-1483534045592",
        "role": "edge",
        "availabilityZone": "us-east-1a",
        "address": "54.152.171.193",
        "state": "inservice",
        "launchConfig": "rajdeep-v2",
        "capacity": 4
      }
    

REST API for Streams

Read Stream

Description

Reads an event stream from system. This read operation provides the client with an origin server address for the given stream name and scope.

Optionally region can also be specified if origin / edge at a specific region is required. If a node is found at the requested region, that will be provided else the next best optimal node will be provided.

  • For Broadcasters the Origin address is used to publish a stream
  • For Subscribers the Origin address helps in looking up a suitable edge address for the stream via Origin API gateway
  • Query parameter region , is used to optionally lookup a node in a specific region for a broadcast or subscribe request. The specified value for region should match the regions supported by your clloud service provider (Google Compute or Amazon Web Services.

If a stream is not publishing, a subscribe type request will result in a http code 400 or 404.

REQUEST

  • URL: Broadcaster

    SIMPLE REQUEST

    http://{host}:{port}/streammanager/api/2.0/event/{scopeName}/{streamName}?action=broadcast

    OR

    REGION PRIORITY REQUEST

    http://{host}:{port}/streammanager/api/2.0/event/{scopeName}/{streamName}?action=broadcast&region={region-code}

    Subscriber

    SIMPLE REQUEST

    http://{host}:{port}/streammanager/api/2.0/event/{scopeName}/{streamName}?action=subscribe

    OR

    REGION PRIORITY REQUEST

    http://{host}:{port}/streammanager/api/1.0/event/{scopeName}/{streamName}?action=subscribe&region={region-code}

  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • DATA:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    

For Broadcaster (i.e., ?action=broadcast)

  • Success: HTTP CODE 200
  • DATA:
      {
        "name": "<stream-name>",
        "scope": "<stream-scope>",
        "serverAddress": "<origin-host-address>",
        "region": "<region-code>"
      }
    

For Subscriber (i.e., ?action=subscribe)

  • Success: HTTP CODE 200
  • DATA:
      {
        "name": "<stream-name>",
        "scope": "<stream-scope>",
        "serverAddress": "<edge-host-address>",
        "region": "<region-code>"
      }
    

Example 1.a - Broadcaster (?action=broadcast)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/live/demo?action=broadcast
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
      {
        "name": "demo",
        "scope": "/live",
        "serverAddress": "104.197.131.87",
        "region": "us-east-1"
      }
    

Example 1.b - Subscriber (?action=subscribe)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/live/demo?action=subscribe
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
      {
        "name": "demo",
        "scope": "/live",
        "serverAddress": "104.197.85.57",
        "region": "us-east-1"
      }
    

Read Stream With Stats

Description

Reads an event stream details from system.

This read operation provides the client with the details of the stream and stats on it.

If a stream is not broadcasting, this operation will result in a 400 or 404 HTTP code.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/{scopeName}/{streamName}/stats
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "name": "<stream-name>",
        "scope": "<stream-scope>",
        "serverAddress": "<origin-host-address>",
        "region": "<region-code>",
        "currentSubscribers": <subscriber-count>,
        "startTime": <start-timestamp>
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/live/demo/stats
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "name": "demo",
        "scope": "/live",
        "serverAddress": "104.197.131.87",
        "region": "us-east-1",
        "currentSubscribers": 0,
        "startTime": 1454369656708
      }
    

List Streams

Description

Reads all active streams the system.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/list
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      [
      {
        "name": "<stream-name>",
        "scope": "<stream-scope>",
        "serverAddress": "<origin-host-address>",
        "region": "region-code>"
      }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/list
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      [
      {
        "name": "demo",
        "scope": "/live",
        "serverAddress": "104.197.131.87",
        "region": "us-east-1"
      }
      ]
    

List All Streams With Stats

Description

Lists all active streams in the system with stats.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/list/stats
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • DATA:
      [
      {
        "name": "<stream-name>",
        "scope": "<stream-scope>",
        "serverAddress": "<origin-host-address>",
        "region": "<region-code>",
        "currentSubscribers": <subscriber-count>,
        "startTime": <start-timestamp>
      }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/event/list/stats
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
      [
        {
          "name": "demo",
          "scope": "/live",
          "serverAddress": "104.197.131.87",
          "region": "us-east-1",
          "currentSubscribers": 0,
          "startTime": 1476179449523
        }
      ]
    

Delete All Streams

Description

Deletes / Clears all stream entries from system. The call is meant for administration / maintainence use.It can be used to forcefully clear stream entries from the system.

This does not change the actual state (publishing) of a stream.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/event?accessToken=<accessToken>
  • Method: DELETE

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "count": <deleted-stream--count>,
        "timestamp": <timestamp>
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/event?accessToken=xyz123
  • Method : DELETE

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "count": 0,
        "timestamp": 1476193803551
      }
    

REST API for Alarms


Get Alarm Threshold

Description

Reads the current alarm threshold value for the system.

This read operation provides the stream manager with the alarm threshold value which is used in autoscaling (scaling-outwards). This value is the default scaleout alarm threshold for all nodegroups.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=<nodeType>&accessToken=<accessToken> FOR EDGE:

    http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=edge&accessToken=<accessToken>

    FOR ORIGIN:

    http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=origin&accessToken=<accessToken>

  • Method: GET
  • Data: Query Param : type Value(s) : edge or origin

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "id": <alarm-id>,,
        "type": "<alarm-type>",
        "metric": "<alarm-metric>",
        "unit": "<alarm-metric-unit>",
        "threshold": <alarm-threshold>,
        "comparator": "<alarm-threshold-comparator>"
        "targetType":  "<alarm-target-type>"
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=edge&accessToken=xyz123
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "id": 1,
        "type": "SCALEOUTALARM",
        "metric": "CONNECTIONS",
        "unit": "PERCENTAGE",
        "threshold": 60,
        "comparator": "GREATERTHAN",
        "targetType": "GROUP"
      }
    

Set Alarm Threshold

Description

Sets the current alarm threshold value for the system.

This write operation provides the stream manager with the alarm threshold value which is used in autoscaling (scaling-outwards). This value is the default scaleout alarm threshold for all nodegroups. The value should be within 1-100 (technically), but recommended values are between 20 and 80 (percentage). The default value for a new setup is 60.

As opposed to previous versions of the Stream Manager, you no longer need to stop the server to update the scaleout alarm threshold value.

This operation should be run only when you have no active traffic on your system. Threshold value should not be updated on live systems.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=<nodeType>&threshold=<threshold>&accessToken=<accessToken> FOR EDGE:

    http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=edge&threshold=<threshold>&accessToken=<accessToken>

    FOR ORIGIN:

    http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=origin&threshold=<threshold>&accessToken=<accessToken>

  • Method: PUT / POST
  • Data: Query Param : type Value(s) : edge or origin

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data:
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "id": <alarm-id>,,
        "type": "<alarm-type>",
        "metric": "<alarm-metric>",
        "unit": "<alarm-metric-unit>",
        "threshold": <alarm-threshold>,
        "comparator": "<alarm-threshold-comparator>"
        "targetType":  "<alarm-target-type>"
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/admin/alarm/scaleout/default?type=edge&threshold=80&accessToken=xyz123
  • Method : PUT

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "id": 1,
        "type": "SCALEOUTALARM",
        "metric": "CONNECTIONS",
        "unit": "PERCENTAGE",
        "threshold": 80,
        "comparator": "GREATERTHAN",
        "targetType": "GROUP"
      }
    

REST API for VOD

The VOD API requires cloud storage for VOD to be configured on your server nodes.


List cloud storage HLS content

Description

Returns list of HLS playlists (m3u8) available on cloud bucket (S3 etc) for playback. These media files are created when a live stream is recorded on Red5 Pro with the 'record' parameter and then moved to cloud storage by Red5 Pro's cloud-storage plugin.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/{scopeName}/playlists OR

    http://{host}:{port}/streammanager/api/2.0/media/{scopeName}/playlists/{subscope}

    If your content was recorded at a sub-scope level of an application, you will need to specify the sub-scope path at the {subscope} placeholder.

  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "playlists": [
          {
            "name": "<playlist-name>",
            "lastModified": <last-modified>,
            "length": <vod-duration>,
            "url": "<playlist-url>"
          }
        ]
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/live/playlists
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "playlists": [
          {
            "name": "stream1.m3u8",
            "lastModified": 1475674784000,
            "length": 210,
            "url": "https://red5vodpro.s3.amazonaws.com/live/stream1/stream1.m3u8"
          }
        ]
      }
    

List cloud storage media files content

Description

Returns list of FLV and MP4 media files available on cloud storage bucket (S3 etc) for playback. These media files are created when a live stream is recorded on Red5 Pro with the record parameter and then is moved to cloud storage by the Red5 Pro cloud-storage writer Post-Processor.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/{scopeName}/mediafiles OR

    http://{host}:{port}/streammanager/api/2.0/media/{scopeName}/mediafiles/{subscope}

    If your content was recorded at a sub-scope level of an application, you will need to specify the sub-scope path at the {subscope} placeholder.

  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "mediafiles": [
          {
            "name": "<media-name>",
            "lastModified": <last-modified>,
            "length": <duration>,
            "url": "<media-url>"
          }
        ]
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/live/mediafiles
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "mediafiles": [
          {
            "name": "stream1.flv",
            "lastModified": 1475674784000,
            "length": 1519198,
            "url": "https://red5vodpro.s3.amazonaws.com/live/streams/stream1.flv"
          }
        ]
      }
    

Cloud storage VOD subscribe

Description

Requests stream-manager for a suitable edge server for media subscription. This is valid for FLV and MP4 media files only and is applicable when using the cloud-storage plugin. The media files are stored on cloud bucket and played back through Red5 Pro.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/{scopeName}/{streamname}.{extension}
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        "name": "<media-name>",
        "scope": "<scope>",
        "serverAddress": "<edge-server-addess>",
        "region": "<region-code>"
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/live/mystream.flv
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
        "name": "mystream.flv",
        "scope": "/live",
        "serverAddress": "104.199.230.92",
        "region": "asia-east1"
      }
    

List active VOD

Description

Lists all VOD streams which have active subscribers.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/list
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      {
        [
        {
          "name": "<media-name>",
          "type": "<media-type>",
          "scope": "<scope>"
        }
      ]
      }
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/1.0/media/list
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      {
      [
        {
          "name": "sample.flv",
          "type": "flv",
          "scope": "/live"
        }
      ]
      }
    

List active VOD with stats

Description

Lists all VOD streams which have active subscribers along with the subscriber count.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/list/stats
  • Method: GET

RESPONSE

  • Failure: HTTP CODE 400 or 404
  • Data :
      {
        "errorMessage": "<error-message-string>",
        "timestamp": <error-timestamp>
      }
    
  • Success: HTTP CODE 200
  • Data:
      [
        {
          "currentSubscribers": <current-subscribers>,
          "name": <media-name>,
          "type": <media-type>,
          "scope": <scope>
        }
      ]
    

Example

REQUEST

  • URI: http://{host}:{port}/streammanager/api/2.0/media/list/stats
  • Method : GET

RESPONSE

  • Success: HTTP CODE 200
  • Data:
      [
        {
          "currentSubscribers": 1,
          "name": "sample.mp4",
          "type": "mp4",
          "scope": "/live"
        }
      ]
    

REST API Glossary

The following glossary explains the Request and Response Parameters provided in the examples above.

group-min-connections

Minimum subscriber connections that this group should support. This parameter helps the scale-in process decide when to scale down an edge.

min-origin-connections

Minimum connections at origin. This should always be zero (0) for the current version of Stream Manager.

launch-config-name

Name of the launch configuration to be used for launching a new instance. Usually this implies the consistent machine configuration for a group. A launch configuration defines your compute machine type, max connections, etc., for an instance.

scale-policy-name

Name of the scale policy to be used by Autoscaler to launch new edges when load conditions occur. A scale policy defines details such as min-max edges allowed, instances warm up time, cooldown period, etc.

stream-name

Name of the stream for publishing or subscription.

stream-scope

Red5 scope where the stream exists. This usually determined by the RTMP connection URL.

origin-host-address

Host address of an available Red5 Pro origin server.

stream-description

Descriptive information about the stream (optional).

region-code

A region code representing the region as suuported by your cloud platform provider.Regions codes generally map your cloud providers's data center(s) at a region.

subscriber-count

Total active subscribers count for this stream.

start-timestamp

Stream start timestamp.

node-identifier

Unique Identifier of a node. Directly translates as virtual machine instance name.

role

Role of the instance in the system: Origin or Edge.

host

Instance host name/address.

node-state

Instance state: RUNNING, TERMINATING, INSERVICE, PENDING, etc.

connection-capacity

Maximum connection capacity of this instance as per launch configuration information.

group-identifier

Group name identifier.

alarm-id

Id of an alarm.

alarm-type

Alarm type. Generally the type will be either scale-out or scale-in.

alarm-metric

Metric that the alarm is set to monitor.

alarm-threshold

Threshold value for the alarm.

alarm-threshold-comparator

The comparator enum for threshold evaluation on this alarm. Comparators are comparision operators used to evaluate conditions at runtime using the threshold values and current value of the targeted metric.

alarm-target-type

Target type enum of the alarm. This is always set to GROUP, In current versions of Stream Manager alarms are meant for groups only.

playlist-name

Name of the VOD m3u8 playlist on cloud storage.

media-file-name

Name of the VOD mp4/flv media on cloud storage.

vod-duration

Time duration of the VOD content (in seconds).

last-modified

Last modified timestamp of the VOD content on cloud.

playlist-url

The absolute HTTP(s) url of the m3u8 playlist.

media-url

The url of the flv/mp4 media file.

error-message-string

Human friendly error message string.

error-timestamp

Timestamp for when the error message was generated.

total-group-connections

Total connections on observed on the node group.

total-node-count

Total nodes in the group. This includes nodes in different states.

total-active-nodes

Total active nodes in the group. This includes nodes in active state (INSERVICE) only.

total-available-capacity

Total available connection capacity of the given node role. This is a cumulative total of invidual node capacities belonging to same node role.

total-connection-load

Total available connection load (count) of the given node role. This is a cumulative total of invidual node capacities belonging to same node role. You can calculate the net percentage using the values of total-available-capacity and total-connection-load.


Additional Documentation

The following documents also pertain to Autoscaling and the Red5 Pro Stream Manager:

> Autoscaling Streams with Red5 Pro

> Red5 Pro Stream Manager User Guide