How to use the Wowza Streaming Cloud REST API

Learn how to get started using the REST API for the Wowza Streaming Cloud™ service, including how to request access to it, how locate and the API and access keys, how to experiment using the sandbox environment, and how to test out the API.

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 the article Wowza Streaming Cloud REST API limits for details.

About the REST API


The Wowza Streaming Cloud REST API uses the Hypertext Transfer Protocol (HTTP) to request data from Wowza Streaming Cloud servers through requests to API endpoints.

Requests in the Wowza Streaming Cloud REST API use JSON syntax for the request body and response. The examples in our articles use a curl command to execute an HTTP method in a Command Prompt or Terminal window. To learn about other methods for testing out the REST API, see Tools for testing the API.

Curl commands use the following general format:

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

HTTP method is the action you're requesting of the resource. Wowza Streaing Cloud uses these HTTP methods:

POST POST 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.
GET GET retrieves records from the resource's database. The GET method returns a response includng detailed information about the queried object or objects. You may need values from a GET response in order to use them in a POST or PATCH request.
PATCH PATCH updates records in the resource's database. Certain attributes can't be updated in a PATCH request and must be defined in an intial POST request. The PATCH method returns a response that indicates that the request was successful and includes the values of updated records.
PUT PUT requests in the Wowza Streaming Cloud REST API start or stop a entity such as a live stream or transcoder. The PUT method response gives information about the entity that was affected.
DELETE DELETE removes the record from the resource's database. The delete method returns a response with no content.

Headers are information that precede the actual HTTP request. Wowza Streaming Cloud REST API requests require headers in key:value pairs. 

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. See Locating and using API and access keys for more information.
wsc-access-key The access key is also a 64-digit alphanumeric string, however, each user creates their own in the Wowza Streaming Cloud web manager. You can enable or disable individual access keys, but they don't expire. See Locating and using API and access keys for more information.
Content-Type application/json (only used for POST and PATCH HTTP methods)

Parameters refine the request and may correspond to options in the Wowza Streaming Cloud web manager. They can also be known as attributes. In JSON syntax, you define a value for each parameter in key:value pairs.

Example of parameters and their assigned values in a JSON object:

{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_central_iowa",
     "delivery_method": "push",
     "name": " MyPassthruTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "passthrough"
   } 
}

Resource, or base URL, is the location of the server receiving the request. In the Wowza Streaming Cloud REST API production environment, the base URL is

https://api.cloud.wowza.com/api/[version]/

Example of a full API request in curl command syntax:

curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_central_iowa",
     "delivery_method": "push",
     "name": " MyPassthruTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "passthrough"
   } 
}' "https://api.cloud.wowza.com/api/[version]/transcoders"

Calls to endpoints that respond with one or more JSON objects (lists) include an array called links in the response. 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/[version]/live_streams"
    },
    {
      "rel":"create",
      "method":"POST",
      "href":"https://api.cloud.wowza.com/api/[version]/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/[version]/live_streams/jfSYg4Fb"
         },
         {
            "rel":"update",
            "method":"PATCH",
            "href":"https://api.cloud.wowza.com/api/[version]/live_streams/jfSYg4Fb"
         },
         {
            "rel":"state",
            "method":"GET",
            "href":"https://api.cloud.wowza.com/api/[version]/live_streams/jfSYg4Fb/state"
         },
         {
            ...
         },
         {
            "rel":"delete",
            "method":"DELETE",
            "href":"https://api.cloud.wowza.com/api/[version]/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 IP addresses for whitelisting from behind a firewall.

API versions


The Wowza Streaming Cloud REST API is periodically versioned. Minor updates are iterated using sequential dot numbers; major versions are iterated using sequential whole numbers. Each version is one of three types:

  • Beta – The beta version contains everything that's in the current version as well as some features and functionality that are still in development. These work-in-progress features aren't fully tested and are subject to change. When we're done testing, we'll promote the beta version to the current version and then create a new beta with new features. You're free to use the beta version for testing and evaluation, but beta versions aren't intended for use in production environments and we caution against using a beta in production. There is only one beta version available at any time.
  • Current – The current version offers the most complete, up-to-date, tested, and stable code base. We strongly recommend using the current version in your production environment. There is only one current version available at any time.
  • Supported – A supported version was current at one time but has been replaced by a newer version of the API. Supported versions don't have the newest features, and may contain features or functions that are outdated and don't offer the most efficient methods for accomplishing your streaming goals. If you're using a supported version, we recommend that you upgrade to the current version, as supported versions will ultimately be deprecated.
  • Deprecated – A deprecated version is out-of-date and can't be guaranteed to work in production environments. If you're using a deprecated version, update to the current version at your earliest convenience.

Note: There are no deprecated versions of the Wowza Streaming Cloud REST API at this time.

See Wowza Streaming Cloud REST API Release Notes for a detailed changelog of updates to each API version.

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 user name and choose API Access.
  2. Click Request an API Key.

Locating and using API and access keys


For security, all requests to the Wowza Streaming Cloud REST API must include 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 user name and choose API Access.

Your API key appears in the middle of the Wowza Streaming Cloud REST API page. Access keys are listed in the Access Keys panel on the left side of the page.

  1. To generate a new access key, click Add Access Key.
  2. Leave Enabled selected so that the key is immediately available, and provide an optional Description. Then, click Add.

Wowza Streaming Cloud generates the key.

You can disable and re-enable the access key at any time, and edit the description.

Important: In example requests shown in our example 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.

The Wowza Streaming Cloud REST API sandbox URL is

https://sandbox.cloud.wowza.com/

Open the API sandbox.

Tools for testing the API


The Wowza Streaming Cloud REST API examples in this documentation site use curl commands. cURL is a command-line tool that allows you to execute HTTP requests. It is native to the Terminal application on OS X, but it requires some installation for use in the Command Prompt on Windows operating systems. To find a download for Windows, see the curl Download Wizard. Responses from curl commands are unformatted JSON. To view JSON responses in a formatted, structured way, use your preferred JSON prettifier tool available online. To review curl command syntax used in our API examples, see About the REST API.

Other options for testing the Wowza Streaming Cloud REST API are GUI-based applications such as Postman or Paw that provide a user-interface and responses in formatted JSON. See documentation for your chosen API testing application for detailed usage information, and note these configuration details:

Authorization No Auth
Headers

wsc-api-key: [api key value for your account]

wsc-access-key: [access key value for your user]

Content-Type: application/json

Body JSON-formatted request body that includes parameters and their assigned values

Example POST request in a GUI-based API test application:

example Postman HTTP request for Wowza Streaming Cloud

More resources



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