Versioned API

Versioned APIs (e.g., Studio DRM and Live Streaming Statistics) allow new features to be introduced to the API without impacting existing implementations.

HTTP Methods

Versioned APIs support the following HTTP methods: GET, POST, PATCH, and DELETE.

Authentication

Authenticate a request by providing a msg and its digital signature.

msg: This JSON object must be Base-64 encoded. It must contain the following parameters:
- _owner: Set this to your user ID.
  Where can I find my user ID?
  1. Load the User Settings page. How?From the main menu, navigate to Settings | User Settings.
  2. Your user ID is listed under the User ID label.
- _timestamp: Set this to the Unix time at which the message was generated.
sig: Set this to the digital signature generated from your API key and the HMAC/SHA256 digest of the msg parameter.

Sample Code

Call the api_auth module (Python 3) to return the message and its signature.

import base64
import os
import zlib, hmac, hashlib, time, json


class APICredentials:
    """
    Stores credentials required to request our API.
    """
    @property
    def user_id(self):
        """
        Set your user ID to the one defined on the User Settings page.
        """
        return "1234567890abcdefghijklmnopqrstu"

    @property
    def secret(self):
        """
        Set your API key to a value defined on the Integration Keys page. 
        """
        return "1234567890abcdefghijklmnopqrstuvwxyz1234"


class APIParams(object):
    """
    Provides API authentication. Learn more at:
        https://docs.edgecast.com/video/#Develop/Versioned-API.htm
    """
    def __init__(self, credentials):
        self.credentials = credentials

    def get_params(self, data):
        """
        Encodes and signs <data> into the expected format and returns it.
        """
        data = self._get_params(**data)
        data.update(data)
        return data

    def _get_msg(self, msg=None):
        """
        Encodes and returns the 'msg' parameter.
        """
        msg = msg if msg else {}

        msg.update({
            '_owner': self.credentials.user_id,
            '_timestamp': int(time.time())
        })

        msg = json.dumps(msg)
        msg_compressed = zlib.compress(msg.encode(), 9)
        return base64.b64encode(msg_compressed).strip()

    def _get_params(self, **msg):
        """
        Returns the message and its signature.
        """
        msg = self._get_msg(msg)

        sig = hmac.new(
            self.credentials.secret.encode(), msg, hashlib.sha256
        ).hexdigest()

        return {
            'msg': msg,
            'sig': sig
        }

For example, the following code snippet submits a GET request by calling the get_params function from the api_auth module:

response = requests.get(
    url, params=APIParams(APICredentials()).get_params({})
)

Error Reporting

If an error occurs, then the response will contain the following properties:

Name	Data Type	Description
error	Integer	Indicates whether an error occurred. Valid values are: 0: The requested endpoint was successfully called. 1: An error occurred. Please see the msg parameter for more information.
msg	List	Provides a description of the error encountered. This parameter is only returned when an error occurred.

Name

Data Type

Description

error

Integer

Indicates whether an error occurred.

Valid values are:

0: The requested endpoint was successfully called.
1: An error occurred. Please see the msg parameter for more information.

msg

List

Provides a description of the error encountered. This parameter is only returned when an error occurred.

Examples

Sample responses for different types of errors are provided below.

Invalid value example:

{
	"msg": [
		"track_type is not valid: Values allowed are ['SD', 'HD', 'AUDIO', 'UHD1', 'UHD2', 'ALL']"
	],
	"error": 1
}

Invalid parameter example:

{
	"msg": [
		"Unrecognized parameter: allowed_play."
	],
	"error": 1
}

Invalid ID example: