REST API for Stream Provisioning

Create Stream Provision

Description

Create a new stream provision for a given Stream and Scope; returns the newly created provision data.

REQUEST

  • URI: http://{host}:{port}/streammanager/api/3.1/admin/event/meta/{scopeName}/{streamName}?accessToken=<accessToken>
  • Method: POST
  • DATA:
{
  "meta": {
      "authentication": {
      "username": "<username>",
      "password": "<password>"
     },
      "stream": [
        {
          "name": "<variant_name>",
          "bandwidth": "<variant_bitrate>",
          "level": "<variant_level>",
          "properties": {}
         }
],
      "georules": {
      "regions": [
        "<location_name>"
      ],
      "restricted": "<restriction_status>"
    },
    "qos": "<QOS-Constant-Index>"
  }
}

RESPONSE

  • Success: HTTP CODE 200
  • DATA:
{
    "name": "<streamName>",
    "scope": "<scopeName>",
    "data": {
       "meta": {
           "authentication": {
                "username": "<username>",
                "password": "<password>"
            },
            "stream": [
                    {
                        "name": "<variant_name>",
                        "bandwidth": <variant_bitrate>,
                        "level": <variant_level>,
                        "properties": {}
                    }
  ],
            "georules": {
                "regions": [
                    "<location_name>"
                ],
                "restricted": "<restriction_status>"
            },
            "qos": <QOS-Constant-Index>
        }
    },
    "updated": <updated-timestamp>
}
  • Failure: HTTP CODE 400 or 404
  • Data:
{
  "errorMessage": "<error-message-string>",
  "timestamp": <error-timestamp>
}

Example

REQUEST URI: https://streammanager.url.com/streammanager/api/3.1/admin/event/meta/live/stream1?accessToken=xyz123

  • Method: POST
  • Data: JSON
{
  "meta": {
      "authentication": {
      "username": "acme",
      "password": "acme!newpass"
     },
    "stream": [{
          "name": "stream1_3",
          "bandwidth": 200000,
          "level": 3,
          "properties": {
          "videoHeight": 320,
          "videoWidth": 240,
          "videoFPS": 15,
        }
        },
        {
          "name": "stream1_2",
          "bandwidth": 500000,
          "level": 2,
          "properties": {
          "videoHeight": 640,
          "videoWidth": 480,
          "videoFPS": 30,
        }
        },
        {
          "name": "stream1_1",
          "bandwidth": 750000,
          "level": 1,
          "properties": {
          "videoHeight": 800,
          "videoWidth": 600,
          "videoFPS": 30,
        }
        }
    ],
      "georules": {
      "regions": [
        "US",
        "UK"
      ],
       "restricted": "false"
    },
    "qos": 3
  }
}

RESPONSE

  • Success: HTTP CODE 201
  • Data:
{
    "name": "stream1",
    "scope": "live",
    "data": {
        "meta": {
            "authentication": {
                "username": "acme",
                "password": "acme!newpass"
            },
            "stream": [
                {
          "name": "stream1_3",
          "bandwidth": 200000,
          "level": 3,
          "properties": {
          "videoHeight": 320,
          "videoWidth": 240,
          "videoFPS": 15,
        }
        },
        {
          "name": "stream1_2",
          "bandwidth": 500000,
          "level": 2,
          "properties": {
          "videoHeight": 640,
          "videoWidth": 480,
          "videoFPS": 30,
        }
        },
        {
          "name": "stream1_1",
          "bandwidth": 750000,
          "level": 1,
          "properties": {
          "videoHeight": 800,
          "videoWidth": 600,
          "videoFPS": 30,
                }
            ],
            "georules": {
                "regions": [
                    "US",
                    "UK"
                ],
                "restricted": "false"
            },
            "qos": 3
        }
    },
    "updated": 1520946314644
}

List Stream Provisions

DESCRIPTION:

Lists the streams that are provisioned through the Stream Manager.

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

METHOD: GET

RESPONSE

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

SUCCESS

CODE: 200
DATA:
{
    "name": "<streamName>",
    "scope": "<scopeName>",
    "data": {
        "meta": {
            "authentication": {
                "username": "<username>",
                "password": "<password>"
            },
            "stream": [
                    {
                        "name": "<variant_name>",
                        "level": <variant_level>,
                        "bandwidth": <variant_bitrate>,
                        "properties": {}
                    }
        ],
            "georules": {
                "regions": [
                    "<location_name>"
                ],
                "restricted": "<restriction_status>"
            },
            "qos": <QOS-Constant-Index>
        }
    },
    "updated": <updated-timestamp>
}

Example: Lists the provisioned streams

REQUEST URI: https://streammanager.url.com/streammanager/api/3.1/admin/event/meta?accessToken=xyz123

Method: GET

RESPONSE

  • Success: HTTP CODE 201
  • Data:
{
    "name": "stream1",
    "scope": "live",
    "data": {
        "meta": {
            "authentication": {
                "username": "acme",
                "password": "acme!newpass"
            },
            "stream": [
                {
                    "name": "stream1_1",
                    "bandwidth": 25000,
                    "level": 3,
                    "properties": {}
                },
                {
                    "name": "stream1_2",
                    "bandwidth": 37500,
                    "level": 2,
                    "properties": {}
                },
                {
                    "name": "stream1_3",
                    "bandwidth": 62500,
                    "level": 1,
                    "properties": {}
                }
            ],
            "georules": {
                "regions": [
                    "US",
                    "UK"
                ],
                "restricted": "false"
            },
            "qos": 3
        }
    },
    "updated": 1520946314644
}

Read Stream Provision

DESCRIPTION:

Reads and returns a stream provision from Stream Manager data store for a given Stream and Scope.

  • URI: http://{host}:{port}/streammanager/api/3.1/admin/event/meta/{scopeName}/{streamName}?accessToken=<accessToken>

METHOD: GET

RESPONSE

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

SUCCESS

CODE: 200
DATA:
{
    "name": "<streamName>",
    "scope": "<scopeName>",
    "data": {
        "meta": {
            "authentication": {
                "username": "<username>",
                "password": "<password>"
            },
            "stream": [
                    {
                        "name": "<variant_name>",
                        "bandwidth": <variant_bitrate>,
                        "level": <variant_level>,
                        "properties": {}
                    }
        ],
            "georules": {
                "regions": [
                    "<location_name>"
                ],
                "restricted": "<restriction_status>"
            },
            "qos": <QOS-Constant-Index>
        }
    },
    "updated": <updated-timestamp>
}

Example: Reads a stream provision data from store

REQUEST URI: https://streammanager.url.com/streammanager/api/3.1/admin/event/meta/live/stream1?accessToken=xyz123

Method: GET

RESPONSE

  • Success: HTTP CODE 201
  • Data:
{
    "name": "stream1",
    "scope": "live",
    "data": {
        "meta": {
            "authentication": {
                "username": "acme",
                "password": "acme!newpass"
            },
            "stream": [
                {
                    "name": "stream1_1",
                    "bandwidth": 25000,
                    "level": 3,
                    "properties": {}
                },
                {
                    "name": "stream1_2",
                    "bandwidth": 37500,
                    "level": 2,
                    "properties": {}
                },
                {
                    "name": "stream1_3",
                    "bandwidth": 62500,
                    "level": 1,
                    "properties": {}
                }
            ],
            "georules": {
                "regions": [
                    "US",
                    "UK"
                ],
                "restricted": "false"
            },
            "qos": 3
        }
    },
    "updated": 1520946314644
}

Read Stream Provision Fragment

Description

Reads and returns a part of the stream provision from Stream Manager data store for a given Stream and Scope by a specified meta ‘key’.

NOTE: The property targeted by the key parameter must exist at the root level, ie: under the meta object.

URI: http://{host}:{port}/streammanager/api/3.1/admin/event/meta/{scopeName}/{streamName}?accessToken=<accessToken>&key=<metaKey>

  • Method: GET

  • Parameters:

| Parameter | Description | Value | | key | Name of a property to be read. This property should exist under the root object meta | A property name string |

RESPONSE

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

SUCCESS

  • CODE: 200
  • DATA:
{
    "name": "<streamName>",
    "scope": "<scopeName>",
    "data": {
        "<key>": {
        <data>
    },
    "updated": <updated-timestamp>
}

Example: Reading global authentication information

URI: https://streammanager.url.com/streammanager/api/3.1/admin/event/meta/live/stream1?accessToken=xyz123&key=authentication

Method: GET

RESPONSE

  • Success: HTTP CODE 201
  • Data:
{
    "name": "stream1",
    "scope": "live",
    "data": {
        "authentication": {
            "username": "acme",
            "password": "acme!newpass"
        }
    },
    "updated": 1520946314644
}

Update Stream Provision

DESCRIPTION

Updates a provision in the Stream Manager data store for a given Stream and Scope with new data and returns the updated provision.

  • URI: http://{host}:{port}/streammanager/api/3.1/admin/event/meta/{scopeName}/{streamName}?accessToken=<accessToken>
  • METHOD: PUT
  • DATA:
{
  "meta": {
    "authentication": {
      "username": "<username>",
      "password": "<password>"
    },
    "stream": [
                    {
                        "name": "<variant_name>",
                        "bandwidth": <variant_bitrate>,
                        "level": <variant_level>,
                        "properties": {}
                    }
      ],
    "georules": {
      "regions": [
        "<location_name>"
      ],
      "restricted": "<restriction_status>"
    },
    "qos": <QOS-Constant-Index>
  }
}

RESPONSE

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

SUCCESS

  • CODE: 200
  • DATA:
{
    "name": "<streamName>",
    "scope": "<scopeName>",
    "data": {
        "meta": {
            "authentication": {
                "username": "<username",
                "password": "<password>"
            },
            "stream": [
                    {
                        "name": "<variant_name>",
                        "bandwidth": <variant_bitrate>,
                        "level": <variant_level>,
                        "properties": {}
                    }
        ],
            "georules": {
                "regions": [
                    "<location_name>"
                ],
                "restricted": "<restriction_status>"
            },
            "qos": <QOS-Constant-Index>
        }
    },
    "updated": <updated-timestamp>
}

Example: Updating authentication password and inverting georule restriction status

  • URI: https://streammanager.url.com/streammanager/api/3.1/admin/event/meta/live/stream1?accessToken=xyz123
  • Method: PUT
  • Data: JSON
{
  "meta": {
    "authentication": {
      "username": "acme",
      "password": "acme!diffpass"
    },
    "stream": [{
          "name": "stream1_1",
          "bandwidth": 25000,
          "level": 3,
          "properties": {

          }
        },
        {
          "name": "stream1_2",
          "bandwidth": 37500,
          "level": 2,
          "properties": {

          }
        },
        {
          "name": "stream1_3",
          "bandwidth": 62500,
          "level": 1,
          "properties": {

          }
        }
    ],
    "georules": {
     "regions": [
        "US",
        "UK"
      ],
      "restricted": "true"
     },
    "qos": 3
  }
}

RESPONSE

  • Success: HTTP CODE 201
  • Data:
{
    "name": "stream1",
    "scope": "live",
    "data": {
        "meta": {
            "authentication": {
                "username": "acme",
                "password": "acme!diffpass"
            },
            "stream": [
                {
                    "name": "stream1_1",
                    "bandwidth": 25000,
                    "level": 3,
                    "properties": {}
                },
                {
                    "name": "stream1_2",
                    "bandwidth": 37500,
                    "level": 2,
                    "properties": {}
                },
                {
                    "name": "stream1_3",
                    "bandwidth": 62500,
                    "level": 1,
                    "properties": {}
                }
            ],
            "georules": {
                "regions": [
                    "US",
                    "UK"
                ],
                "restricted": "true"
            },
            "qos": 3
        }
    },
    "updated": 1520947709222
}

Delete Stream Provision

DESCRIPTION

Deletes a stream provision from Stream Manager data store by a given Stream and Scope and returns the deleted provision data.

  • URI: http://{host}:{port}/streammanager/api/3.1/admin/event/meta/{scopeName}/{streamName}?accessToken=<accessToken>
  • METHOD: DELETE

RESPONSE

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

SUCCESS

  • CODE: 200
  • DATA:
{
    "name": "<streamName>",
    "scope": "<scopeName>",
    "data": {
        "meta": {
            "authentication": {
                "username": "<username",
                "password": "<password>"
            },
            "stream": [
                    {
                        "name": "<variant_name>",
                        "bandwidth": <variant_bitrate>,
                        "level": <variant_level>,
                        "properties": {}
                    }
       ],
            "georules": {
                "regions": [
                    "<location_name>"
                ],
                "restricted": "<restriction_status>"
            },
            "qos": <QOS-Constant-Index>
        }
    },
    "updated": <updated-timestamp>
}

Example: Deletes the stream provision created earlier

  • URI: https://streammanager.url.com/streammanager/api/3.1/admin/event/meta/live/stream1?accessToken=xyz123
  • Method: DELETE

RESPONSE

  • Success: HTTP CODE 201
  • Data:
{
    "name": "stream1",
    "scope": "live",
    "data": {
        "meta": {
            "authentication": {
                "username": "acme",
                "password": "acme!newpass"
            },
            "stream": [
                {
                    "name": "stream1_1",
                    "bandwidth": 25000,
                    "level": 3,
                    "properties": {}
                },
                {
                    "name": "stream1_2",
                    "bandwidth": 37500,
                    "level": 2,
                    "properties": {}
                },
                {
                    "name": "stream1_3",
                    "bandwidth": 62500,
                    "level": 1,
                    "properties": {}
                }
            ],
            "georules": {
                "regions": [
                    "US",
                    "UK"
                ],
                "restricted": "false"
            },
            "qos": 3
        }
    },
    "updated": 1520947709222
}

Parameters Index

Parameter Description Value Type
streamName The name of the stream for which the data is being provisioned Alphabetic string
scopeName The scopename of the stream for which the data is being provisioned Alphabetic string
meta Top level object for provisioning data NA
authentication Global object containing publisher credentials information for the stream NA
username Username for publisher Alphanumeric string
password Password for publisher Alphanumeric string
stream Master object array with description of stream variants NA
stream=> name Stream variant name Alphabetic string
stream=> bandwidth Stream variant bitrate Numeric value representing bitrate inbytes per second. This property is optional but can be useful if we need to provide bitrate information to a client, that is unable to guess the stream ‘level’. (Optional)
stream=> level Specifies the level for this variant. Higherbitrate streams must havelowerlevel number. Numbering starts from 1 onwards. This is used for abr switching. For a single stream the level should be 0. Numeric positive integer
stream=> properties Additional stream properties holder object for a variant stream. You can override the Global‘authentication’,‘georule’and‘qos’settings by providing an alternate copy of the appropriate object that you need to override inside the‘properties’object. NA
georules Master object containing geo restrictions information NA
georules => regions An array of region / location identifiers Alphanumeric String (supports hyphens)
georules => restricted Indicates whether the location identifiers are inclusive or exclusive Boolean true/false
qos Network QOS value for the Stream Qos value should represent the index of the QOS content intended. (See below)

QOS Constants Index:

QOS Content Index Java Value
IPTOS_LOWCOST 0 0x02
IPTOS_RELIABILITY 0x04
IPTOS_THROUGHPUT 0x08
IPTOS_LOWDELAY 0x10

Additional Notes

  • meta is the top level object for a stream provision. Stream properties such as authentication, georules or qos which exist at this level are treated as global. Ie, they are automatically copied over to each stream variant unless an override exists.
  • Individual stream objects can include additional custom properties. The json is not validated for custom property names, thus making it flexible for new properties to be added.
  • bandwidth property is optional. Streams are validated by the value of their level attribute. Higher quality stream variant should specify a lower value for the level attribute. Level values start from 1.
  • Stream properties is an optional placeholder to help the provisioner to specify any optional data for a variant. It may also contain its own authentication, georules or qos object. This can be used to override the master authentication, georules and qos object definitions specified at top level directly under the meta object.

Overriding Properties

Global properties can be overridden for a stream variant by specifying the same property in the ‘stream’ variant’s properties container.

EXAMPLE: The following example demonstrates how to specify a different ‘qos’ value for a particular stream variant by name ‘stream_3’.

  • URI: http://{host}:{port}/streammanager/api/3.1/admin/event/meta/live/stream1?accessToken=xyz123
  • Method: POST
  • Data: JSON
{
    "meta": {
       "authentication": {
          "username": "acme",
          "password": "acme!newpass"
       },
       "stream": [{
                 "name": "stream_1",
                 "bandwidth": 25000,
                 "level": 3,
                 "properties": {
                 }
             },
             {
                 "name": "stream_2",
                 "bandwidth": 37500,
                 "level": 2,
                 "properties": {
                 }
             },
             {
                 "name": "stream_3",
                 "bandwidth": 62500,
                 "level": 1,
                 "properties": {
                    "qos": 1
               }
             }
       ],
       "georules": {
         "regions": [
            "US",
             "UK"
          ],
          "restricted": "false"
       },
       "qos": 3
    }
}