• How to use the Wowza Streaming Cloud REST API

    Learn how to get started using the REST API for the Wowza Streaming Cloud™ service.

    Note: Trial users can access the Wowza Streaming Cloud REST API sandbox but not the production API. Reasonable resource limits are in place to prevent excessive usage of streams and stream targets through the Wowza Streaming Cloud REST API. See Wowza Streaming Cloud REST API limits for details.

    Contents


    About the REST API
    Requesting access to the API
    Locating and using API and access keys
    Using the API sandbox
    Documentation

    About the REST API


    The Wowza Streaming Cloud REST API uses the Hypertext Transfer Protocol (HTTP) to request data from Wowza Streaming Cloud servers. The examples in our articles use the curl command to execute an HTTP method in a Command Prompt or Terminal window.

    All requests in the Wowza Streaming Cloud REST API use JSON syntax and the following general format:

    curl -[HTTP method] --[headers] -[parameters] "[resource]"
    Where:

    Headers are information that precede the actual HTTP request. All Wowza Streaming Cloud REST API requests require two custom headers:

    • wsc-api-key – A unique, 64-digit alphanumeric string. Each Wowza Streaming Cloud account has one API key. The API key can't be edited or deleted, and it doesn't expire.

    • wsc-access-key – The access key is also a 64-digit alphanumeric string, however, each user creates their own, and each access key has a limited lifespan. When an access key expires, you have to create a new one.

    HTTP method is the action you're requesting of the resource. For the main tasks in most articles, the HTTP method is POST, which creates records in the resource’s database. The POST method returns a response that indicates that the request was successful and includes the values of any newly created records.

    Parameters refine the request and correspond to options in the Wowza Streaming Cloud web manager.

    Resource is the location where you're sending the request. In the Wowza Streaming Cloud REST API, the base resource is the path

    https://api.cloud.wowza.com/api/v1/

    Calls to endpoints that respond with one or more JSON objects (lists) include an array called links. These links provide additional information about the endpoint, such as what other URLs are available and what can be done next for the resource, to help reduce the need to consult documentation. For calls that return a list of objects, the links array looks like this:

    {
      "live_streams": [
        {...},
        {...}
      ],
      "links": [
        {
          "rel":"self",
          "method":"GET",
          "href":"https://api.cloud.wowza.com/api/v1/live_streams"
        },
        {
          "rel":"create",
          "method":"POST",
          "href":"https://api.cloud.wowza.com/api/v1/live_streams"
        }
      ]
    }
    For calls that return details of an object, the links array looks like this:

    {  
       "live_stream":{  
          "id":"jfSYg4Fb",
          "name":"My Live Stream",
          "...": "..."
          "links":[  
             {  
                "rel":"self",
                "method":"GET",
                "href":"https://api.cloud.wowza.com/api/v1/live_streams/jfSYg4Fb"
             },
             {  
                "rel":"update",
                "method":"PATCH",
                "href":"https://api.cloud.wowza.com/api/v1/live_streams/jfSYg4Fb"
             },
             {
                "rel":"state",
                "method":"GET",
                "href":"https://api.cloud.wowza.com/api/v1/live_streams/jfSYg4Fb/state"
             },
             {
                ...
             },
             {  
                "rel":"delete",
                "method":"DELETE",
                "href":"https://api.cloud.wowza.com/api/v1/live_streams/jfSYg4Fb"
             }
          ]
       }
    }
    Note: The Wowza Streaming Cloud REST API publishing and playback endpoints use dynamic IP addresses. As a result, we can't provide network administrators with IP addresses for whitelisting from behind a firewall.

    Requesting access to the API


    You can request access to the Wowza Streaming Cloud REST API through the Wowza Streaming Cloud web manager.

    1. In the menu bar, click your email address and choose API Access.



    2. Click Request an API Key.

    Locating and using API and access keys


    For security, all curl requests in the Wowza Streaming Cloud REST API must be preceded by an API key and an access key, which authenticate your requests to the Wowza Streaming Cloud service.

    Both the API key and the access key can be found in the Wowza Streaming Cloud web manager.

    1. In the menu bar, click your email address and choose API Access.

      Your API key is displayed on the Wowza Streaming Cloud REST API page.



      Access keys are listed in the Access Keys panel on the left side of the page.

    2. To generate a new access key, click Add Access Key.

    3. In example requests shown in our workflow articles—and in your own code—for [key], substitute your API key or your access key, as appropriate.

    Using the API sandbox


    You can explore the Wowza Streaming Cloud REST API using the API sandbox. The API sandbox allows you to test and develop streaming workflows in a safe, separate environment that doesn't affect your Wowza Streaming Cloud production environment. The sandbox is fully functional and can do everything that the real API does, except that it creates simulated live streams and transcoders, not real ones. Because the sandbox doesn't use real resources, you don't accrue charges when you use it.

    Open the API sandbox.

    Documentation


    Complete interactive documentation for the Wowza Streaming Cloud REST API is available at https://sandbox.cloud.wowza.com/apidocs/v1/. The documentation includes definitions of all parameters and commands, the model schema, examples, descriptions of error codes, and the ability to generate test code.

    An example application for the Wowza Streaming Cloud REST API, written in Ruby, is on GitHub.

    In addition, the following articles describe some common tasks and workflows that can be expedited by using the Wowza Streaming Cloud REST API.



    Originally Published: 01-21-2016.
    Updated: 09-08-2016.

    If you're having problems or want to discuss this article, post in our forum.