Media Services On Demand RTMP API v1

Use Real Time Messaging Protocol (RTMP) to configure Media Services On Demand (MSOD) audio, video, and data streams.

Learn more:


Overview

The Media Services On Demand RTMP API lets you to build a customized RTMP streaming interface.

With this API, you can stream audio, video, and data between Flash players and servers.

Who should use this API

Developers and architects can use this API to access and provision media streaming using customized interfaces.

Get started

To configure the Media Services API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named On Demand RTMP Provision, and set the access level to READ-WRITE.

  • If you need help, provide feedback to the Akamai developer community, or contact your Akamai representative for support.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List configurations GET /rtmp-ondemand/v1/configuration
Create a configuration POST /rtmp-ondemand/v1/configuration
Get a configuration GET /rtmp-ondemand/v1/configuration/{cpcode}
Update a configuration PUT /rtmp-ondemand/v1/configuration/{cpcode}
Delete a configuration DELETE /rtmp-ondemand/v1/configuration/{cpcode}
List RTMP CP codes GET /rtmp-ondemand/v1/cpcode
List storage groups GET /rtmp-ondemand/v1/storage-group

List configurations

Retrieves a set of all RTMP configurations available to you.

GET /rtmp-ondemand/v1/configuration

Status 200 application/json

Object type: Configuration

Download schema: getRTMPConfigurationsListDTO.json

Response Body:

{
    "configurations": [
        {
            "swfLocation": "123456.download.example.com/123456/",
            "isSecure": false,
            "name": "testConfig",
            "cpcode": 654321,
            "usePreSpreadSerial": true,
            "hostAliases": [
                "default.host.net (default)"
            ],
            "appNameAliases": [
                "appname1",
                "ondemand"
            ],
            "isRtmpe": true,
            "isMbr": true
        }
    ]
}

Create a configuration

Provisions a new RTMP configuration.

POST /rtmp-ondemand/v1/configuration

Content-Type: application/json

Object type: Configuration

Download schema: putRTMPConfigurationDTO.json

Request Body:

{
    "name": "testConfig123",
    "cpcode": 12345,
    "usePreSpreadSerial": true,
    "hostAliases": [
        "testHost1",
        "testHost2",
        "testHost3"
    ],
    "isRtmpe": false,
    "isMbr": false,
    "isSecure": true,
    "swfPath": "temp",
    "swfLocation": "123456.download.example.com/123456/",
    "authProfiles": [
        {
            "eTokenType": "NEW",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "name": "temp",
            "password": "abc123",
            "cidr": "1.2.3.4/32"
        }
    ],
    "appNameAliases": [
        "ondemand",
        "appname1"
    ],
    "virtualPaths": [
        {
            "name": "path1",
            "domain": "yourdomain.com",
            "location": "location1/location2"
        }
    ]
}

Status 200

Headers:

Location: /configuration/123

Get a configuration

Retrieves detailed information about the requested RTMP configuration.

GET /rtmp-ondemand/v1/configuration/{cpcode}

Sample: /rtmp-ondemand/v1/configuration/123456

Parameter Type Sample Description
URL parameters
cpcode Integer 123456 Unique identifier for each RTMP configuration.

Status 200 application/json

Object type: Configuration

Download schema: putRTMPConfigurationDTO.json

Response Body:

{
    "name": "samplename",
    "cpcode": 12345,
    "isSecure": true,
    "authProfiles": [
        {
            "name": "temp",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": false,
            "requirePayload": true,
            "cidr": "1.2.3.4-4.5.6.7"
        }
    ],
    "usePreSpreadSerial": true,
    "hostAliases": [
        "default.hostname.net (default)",
        "testHost1.com",
        "testHost2.com"
    ],
    "appNameAliases": [
        "ondemand",
        "appname1"
    ],
    "virtualPaths": [
        {
            "name": "path1",
            "domain": "yourdomain.com",
            "location": "location1/location2"
        }
    ],
    "swfPath": "check123",
    "swfLocation": "654321.download.example.com/654321/",
    "isRtmpe": true,
    "isMbr": true
}

Update a configuration

Updates specified fields of an existing RTMP configuration.

PUT /rtmp-ondemand/v1/configuration/{cpcode}

Sample: /rtmp-ondemand/v1/configuration/123456

Content-Type: application/json

Object type: Configuration

Download schema: putRTMPConfigurationDTO.json

Request Body:

{
    "name": "sampleConfig",
    "cpcode": 1234,
    "usePreSpreadSerial": true,
    "isRtmpe": true,
    "isMbr": true,
    "isSecure": true,
    "hostAliases": [
        "testHost1",
        "testHost2"
    ],
    "swfPath": "check123",
    "swfLocation": "654321.download.example.com/654321/",
    "authProfiles": [
        {
            "name": "tempAuthProf",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "cidr": "1.2.3.4-1.2.3.4"
        }
    ],
    "appNameAliases": [
        "ondemand",
        "appname1"
    ],
    "virtualPaths": [
        {
            "name": "path1",
            "domain": "yourdomain.com",
            "location": "location1/location2"
        }
    ]
}
Parameter Type Sample Description
URL parameters
cpcode Integer 123456 Unique identifier for each RTMP configuration.

Status 200

Delete a configuration

Deletes an existing RTMP configuration.

DELETE /rtmp-ondemand/v1/configuration/{cpcode}

Sample: /rtmp-ondemand/v1/configuration/123456

Parameter Type Sample Description
URL parameters
cpcode Integer 123456 Unique identifier for each RTMP configuration.

Status 200

List RTMP CP codes

Obtains available CP codes for new RTMP configurations.

GET /rtmp-ondemand/v1/cpcode

Status 200 application/json

Object type: CpCode

Download schema: RTMPCpcodesDTO.json

Response Body:

{
    "used": [
        {
            "cpcode": 12345,
            "name": "cpcode1"
        },
        {
            "cpcode": 54321,
            "name": "cpcode2"
        },
        {
            "cpcode": 67890,
            "name": "cpcode3"
        }
    ],
    "unused": [
        {
            "cpcode": 24680,
            "name": "cpcode4"
        },
        {
            "cpcode": 13579,
            "name": "cpcode5"
        },
        {
            "cpcode": 21345,
            "name": "cpcode6"
        }
    ]
}

List storage groups

Provides a list of storage groups.

GET /rtmp-ondemand/v1/storage-group

Status 200 application/json

Object type: StorageGroup

Download schema: RTMPStorageGroupDTO.json

Response Body:

[
    {
        "cpcode": 123456,
        "downloadDomain": "123456.download.example.com",
        "location": "123456.download.example.com/123456/"
    },
    {
        "cpcode": 654321,
        "downloadDomain": "654321.download.example.com",
        "location": "654321.download.example.com/654321/"
    },
    {
        "cpcode": 246813,
        "downloadDomain": "246813.download.example.com",
        "location": "246813.download.example.com/246813/"
    }
]

Data

This section provides you with the data model for the MSOD RTMP API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

Configuration

When you create a configuration, choose the appropriate origin for your stream, either your own origin or an Akamai NetStorage origin. In a NetStorage origin, the domain is already added in the ACL list for Akamai to identify that it’s a trusted domain.

Download schema: postRTMPConfigurationDTO.json

Sample POST request:

{
    "name": "testConfig123",
    "cpcode": 12345,
    "usePreSpreadSerial": true,
    "hostAliases": [
        "testHost1",
        "testHost2",
        "testHost3"
    ],
    "isRtmpe": false,
    "isMbr": false,
    "isSecure": true,
    "swfPath": "temp",
    "swfLocation": "123456.download.example.com/123456/",
    "authProfiles": [
        {
            "eTokenType": "NEW",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "name": "temp",
            "password": "abc123",
            "cidr": "1.2.3.4/32"
        }
    ],
    "appNameAliases": [
        "ondemand",
        "appname1"
    ],
    "virtualPaths": [
        {
            "name": "path1",
            "domain": "yourdomain.com",
            "location": "location1/location2"
        }
    ]
}

Configuration members

Member Type Required Description
Configuration: When you create a configuration, choose the appropriate origin for your stream, either your own origin or an Akamai NetStorage origin. In a NetStorage origin, the domain is already added in the ACL list for Akamai to identify that it’s a trusted domain.
appNameAliases Array Specify the RTMP app name aliases that enable you to use multiple app names.
authProfiles Configuration.authProfiles[] Authorization profiles that can access the configuration or the stream.
cpcode Integer The Content Provider code name that you use to provision your RTMP configuration.
createdDate String Read-only. The date and time when the RTMP configuration was created. It’s an ISO 8601 timestamp.
hostAliases Array You link these aliases to the default hostname. To stream content using these hostnames, create them on your DNS server as CNAME records pointing to the default hostname.
isHDConfig Boolean When enabled, it assigns the stream packaging type to your configuration.
isMbr Boolean Enables the Dynamic/MBR (multiple bit rate) feature for your stream.
isRtmpe Boolean Enables use of RTMPE/RTMPTE protocols. This denies all other protocols (RTMP/RTMPT).
isSecure Boolean Enables secure streaming, which ensures that only authorized users can access or download your media content.
name String The unique name that you create for your configuration.
swfLocation String NetStorage location to which you upload your authorized SWF files. Streaming uses these to verify the validity of the SWF files requesting videos associated with the Flash configuration.
swfPath String NetStorage location to which you upload your authorized SWF files. The streaming process uses these to validate the SWF files requesting videos in the Flash configuration.
usePreSpreadSerial Boolean Specify whether to use the standard protocol port for streaming.
Configuration.authProfiles[]: Authorization profiles that can access the configuration or the stream.
cidr String This option can be used if you would like to restrict viewing of a stream to end users in a certain IP range or CIDR block.
eTokenType Enumeration Specifies whether to create a new E-Token (NEW), keep the same E-Token (NO_CHANGE), or disable (DISABLE) an existing E-token. Enabling E-type token requires inclusion of a Rijndael key in your token. For details about E-tokens, see the Secure Streaming Integration Guide.
name String The unique name provided to the authorization profile, not more than 30 characters. If the auth profile names are duplicated then you can’t edit the profiles.
password String Password for each auth profile. Passwords can be made up of any character type, but must be no more than 10 characters.
requireIP Boolean Specify whether the authorization profile includes IP addresses in all tokens.
requirePath Boolean The path value in the token ties the token to a particular stream or piece of content. If you remove the path from the token, it reduces the token’s security.
requirePayload Boolean Enabling this value will reject any token that does not include a payload field.

StorageGroup

You can keep your content for distribution in a storage group.

Download schema: RTMPStorageGroupDTO.json

Sample GET response:

[
    {
        "cpcode": 123456,
        "downloadDomain": "123456.download.example.com",
        "location": "123456.download.example.com/123456/"
    },
    {
        "cpcode": 654321,
        "downloadDomain": "654321.download.example.com",
        "location": "654321.download.example.com/654321/"
    },
    {
        "cpcode": 246813,
        "downloadDomain": "246813.download.example.com",
        "location": "246813.download.example.com/246813/"
    }
]

StorageGroup members

Member Type Description
StorageGroup: You can keep your content for distribution in a storage group.
cpcode Integer The Content Provider code that Akamai supplies for RTMP streaming. You use CP codes in the Akamai system to track and report delivered services.
downloadDomain String The hostname of the machine in which you download the storage group and manage its content.
location String The storage group hostname and URL path.

CpCode

The list of used and unused Content Provider codes for creating RTMP configurations or streams. CP codes help you track and report delivered services. Akamai supplies CP codes to you for your product. You cannot create two MSOD RTMP configurations based on the same CP code.

Download schema: RTMPCpcodesDTO.json

Sample GET response:

{
    "used": [
        {
            "cpcode": 12345,
            "name": "cpcode1"
        },
        {
            "cpcode": 54321,
            "name": "cpcode2"
        },
        {
            "cpcode": 67890,
            "name": "cpcode3"
        }
    ],
    "unused": [
        {
            "cpcode": 24680,
            "name": "cpcode4"
        },
        {
            "cpcode": 13579,
            "name": "cpcode5"
        },
        {
            "cpcode": 21345,
            "name": "cpcode6"
        }
    ]
}

CpCode members

Member Type Description
CpCode: The list of used and unused Content Provider codes for creating RTMP configurations or streams. CP codes help you track and report delivered services. Akamai supplies CP codes to you for your product. You cannot create two MSOD RTMP configurations based on the same CP code.
unused CpCode.unused[] The list of unused CP codes available to provision RTMP configurations and streams.
used CpCode.used[] The list of CP codes already in use in the system.
CpCode.unused[]: The list of unused CP codes available to provision RTMP configurations and streams.
cpcode Integer A CP code available for use.
name String The name assigned to the unused CP code.
CpCode.used[]: The list of CP codes already in use in the system.
cpcode Integer A CP code that is already in use.
name String The CP code name.

Errors

This section details the Media Services API error response formats, lists specific error messages you might encounter, and the API’s complete range of HTTP response codes.

Error responses

This API’s error responses conform to the JSON problem specification. The following shows a typical Media Services API error response:

{
    "type": "https://problems.luna.akamaiapis.net/-/resource-impl/forward-origin-error",
    "title": "Bad Request",
    "status": 400,
    "instance": "https://akab-we62bufgzvfmaj5f-3rtepafiil5ulp4p.luna.akamaiapis.net/config-media-live/v1/live/abcd-lh.akamaihd.n1et/stream",
    "method": "GET",
    "serverIp": "184.1.2.3",
    "clientIp": "60.2.3.4",
    "requestId": "14d35d3a",
    "requestTime": "2016-04-19T13:04:20Z"
}

HTTP status codes

The API produces the following set of HTTP status codes for both success and failure scenarios.

Code Description
200 Request OK
201 Resource Created
400 Bad Request
401 Unauthorized Request
402 Failed Request
403 Forbidden
404 Resource not found
405 Method not allowed
415 Unsupported Media Type
422 Unprocessable entity
429 Too many requests
500 Server Error

Last modified: 3/13/2019