/

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.

To help select nodes from a geographically, Stream Manager allows you to specify two geo info query parameters.

  • region : The region query parameter can 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.
  • geozone : The geozone query parameter can be specified to target one or more regions as grouped under the geozone. A geozone is a macro location concept such as a continent, which can be used to group one or more regions together.

The region and geozone parameters are mutually exclusive. If region is specifed, the geozone defaults to global and if the geozone parameter is specified, the region(s) will be determined by what regions are grouped under the geozone. If the Geo Information has not been provisoned and the geozone is specified, it will result in a user error.

  • 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 cloud 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/3.1/event/{scopeName}/{streamName}?action=broadcast

OR

REGION SPECIFIC REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&region={regionName}

OR

REGION STRICT REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&region={regionName}&strict=true

In using strict with this request, the broadcast will not be executed if the region specified does not have any live nodes.

OR

GEOZONE SPECIFIC REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&geozone={geozoneCode}

OR

GEOZONE STRICT REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&geozone={geozoneCode}&strict=true

This request requires that the geo information should have been provisioned in Stream Manager about target geozones nd what regions they include.

  • When you specify endpoints > 0 along with strict=true in a geozone request, Stream Manager will try to collect {endpoints} number of origins/edges while attempting to utilize each region in the geozone only once. The request will succeed only if each region of the geozone can provide one node (without repeatition) and the requested number of endpoints does not exceed the total number of regions in the geozone.
  • When you specify endpoints > 0 along with strict=false in a geozone request, Stream Manager will try to collect {endpoints} number of origins/edges from any regions in the geozone without any specific considerations. If however all the regions of the geozone together cannot provide the minimum required endpoints, the request will fail.

OR

MULTI ORIGIN REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&endpoints={count}

Where count corresponds to the number of origins that are needed for the broadcast stream. The attribute accepts a numeric value starting from 1. If the attribute is skipped the count assumes the value of 1, thereby returning one server endpoint for ingest. For count >1 Stream Manager returns an array response whereas for count = 1, a single object is returned. With the strict flag, the request will fail if the number of nodes existing do not match the number requested.

MULTI ORIGIN STRICT REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&endpoints={count}&strict=true

Where count corresponds to the number of origins that are needed for the broadcast stream. The attribute accepts a numeric value starting from 1. If the attribute is skipped the count assumes the value of 1, thereby returning one server endpoint for ingest. For count >1 Stream Manager returns an array response whereas for count = 1, a single object is returned. With the strict flag, the request will fail if the number of nodes existing do not match the number requested.

OR

TRANSCODER REQUEST

NOTE: The transcoder broadcast will generate additional multiple bitrate stream variants based off of the original stream (which in turn is used for adaptive bitrate subscription). Before you make a transcode broadcast request, you must create a Stream Provision with the additional bitrate and resolution settings.

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=broadcast&transcode=true

This request should return a Transcoder node IP address. Note: if you have not provisioned the stream name, then this request will return an Origin server IP address.

Subscriber

SIMPLE REQUEST

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

OR

REGION SPECIFIC REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe&region={regionName}

OR

REGION STRICT REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe&region={regionName}&strict=true

In using strict with this request, the broadcast will not be executed if the region specified does not have any live nodes.

OR

MULTI EDGE REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe&endpoints={count}

OR

MULTI EDGE STRICT REQUEST

http://{host}:{port}/streammanager/api/3.1/event/{scopeName}/{streamName}?action=subscribe&endpoints={count}&strict=true

Where count corresponds to the number of edges that are needed for subscribing to the stream. The attribute accepts a numeric value starting from 1. If the attribute is skipped the count assumes the value of 1, thereby returning one server endpoint for ingest. For count >1 Stream Manager returns an array response whereas for count = 1, a single object is returned. With the strict flag, the request will fail if the number of nodes existing do not match the number requested.

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 Broadcaster (?action=broadcast)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/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 Subscriber (?action=subscribe)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/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 event stream details from system. If a stream is not broadcasting, this operation will result in a 400 or 404 HTTP code.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/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/3.1/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 streams active in the system.

REQUEST

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

RESPONSE

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

Example

REQUEST

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

RESPONSE

  • Success: HTTP CODE 200
  • Data:
    [
    {
        "type": "origin",
        "name": "stream1",
        "scope": "live",
        "serverAddress": "34.200.228.163",
        "region": "us-east-1"
    },
    {
        "type": "edge",
        "name": "stream1",
        "scope": "live",
        "serverAddress": "34.238.220.153",
        "region": "us-east-1"
    }
    ]

List All Streams With Stats

Description

Lists all active streams in the system with stats. This api call can produce two different kinds of results - aggregated and non-aggregated.Aggregated result displays list of publishing streams (streams at origin) and renders the value of currentSubscribers as the net total of individual currentSubscribers values taken from each edge of the nodegroup.Non-Aggregated result displays streams list for each node (origin & edge) that the stream resides on, with the currentSubscribers value corresponding only to that node.

The optional boolean query parameter aggregate is used to differentiate between aggregated & non-aggregated stats request.A value of true will specify request for aggregated stats whereas a value of false implies a non-aggregated stats request. If the parameter is not specified it defaults to true.

AGGREGATED STATS REQUEST

http://{host}:{port}/streammanager/api/3.1/event/list/stats

OR

NON-AGGREGATED STATS REQUEST

http://{host}:{port}/streammanager/api/3.1/event/list/stats?aggregate=false

For Aggregated Stats (default)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/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>",
      "type": "<node-role>",
      "region": "<region-code>",
      "currentSubscribers": <aggregate-subscriber-count>,
      "startTime": <start-timestamp>
    }
    ]

Example

REQUEST

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

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
    [
    {
        "currentSubscribers": 0,
        "startTime": 1545130249838,
        "type": "origin",
        "name": "stream1",
        "scope": "live",
        "serverAddress": "100.27.43.27",
        "region": "us-east-1"
    },
    {
        "currentSubscribers": 1,
        "startTime": 1545130259426,
        "type": "edge",
        "name": "origin",
        "scope": "live",
        "serverAddress": "100.27.43.27",
        "region": "us-east-1"
    }
    ]

For Non-Aggregated Stats (i.e., ?aggregate=false)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/event/list/stats?aggregate=false
  • 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": "<node-host-address>",
      "type": "<node-role>",
      "region": "<region-code>",
      "currentSubscribers": <subscriber-count>,
      "startTime": <start-timestamp>
    }
    ]

Example

REQUEST

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

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
    [
    {
        "currentSubscribers": 0,
        "startTime": 1545130249838,
        "type": "origin",
        "name": "stream1",
        "scope": "live",
        "serverAddress": "100.27.43.27",
        "region": "us-east-1"
    },
    {
        "currentSubscribers": 0,
        "startTime": 1545130249838,
        "type": "edge",
        "name": "stream1",
        "scope": "live",
        "serverAddress": "34.237.139.9",
        "region": "us-east-1"
    },
    {
        "currentSubscribers": 0,
        "startTime": 1545130259426,
        "type": "origin",
        "name": "stream2",
        "scope": "live",
        "serverAddress": "100.27.43.27",
        "region": "us-east-1"
    },
    {
        "currentSubscribers": 0,
        "startTime": 1545130259426,
        "type": "edge",
        "name": "stream2",
        "scope": "live",
        "serverAddress": "34.237.139.9",
        "region": "us-east-1"
    }
    ]

Delete All Streams

Description

Deletes/Clears all inactive stream entries from the system. The call is meant for administration/maintenance use. It can be used to forcefully clear stream entries that are "stuck" in the system. Using the optional query param includeActive in the api request, you can also force it to remove active stream entries (entried for healthy live streams). NOTE: If you delete active streams, although it does not actually change the state of the live stream, it will make it imposssible for any new subscribers to be added to that stream going through Stream Manager, and additionally that stream will not be listed under the event/list.

CLEAR INACTIVE STREAM ENTRIES

http://{host}:{port}/streammanager/api/3.1/admin/event?accessToken=<accessToken>

CLEAR ALL STREAM ENTRIES

http://{host}:{port}/streammanager/api/3.1/admin/event?includeActive=true&accessToken=<accessToken>

For Removing Inactive Stream Entries (default behaviour)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/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/3.1/admin/event?accessToken=xyz123
  • Method : DELETE

RESPONSE

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

For Removing All Stream Entries (?includeActive=true)

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/admin/event?includeActive=true&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/3.1/admin/event?includeActive=true&accessToken=xyz123
  • Method : DELETE

RESPONSE

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