Query the Wowza Streaming Engine REST API

Wowza Streaming Engine™ 4.3 or later media server software includes a RESTful Application Programming Interface (API) that you can use to configure, manage, and monitor a media server through HTTP requests. Two common query languages to use to execute HTTP requests are cURL and PHP.

Base URL


The resource is the HTTP endpoint that receives your request. In the Wowza Streaming Engine REST API, all resources are accessed through a base URL in the following format:

http://[your-wowza-server]:8087/v2/[path-to-resource]

Resource path substitutions


In REST API endpoints, values shown inside curly brackets {} are placeholders. You must replace these placeholders with your actual values when making a request.

For example, in the following endpoint:

http://localhost:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/{appName}
  • localhost - The IP address of your Wowza Streaming Engine server. We generally use localhost in our curl examples.
  • {serverName} - The name of your Wowza Streaming Engine server. The default value is _defaultServer_.
  • {vhostName} - The name of your virtual host (VHost). The default value is _defaultVHost_.
  • {appName} - The name of your Wowza Streaming Engine application. There's no default value, but we sometimes use testlive in our curl examples.

The final endpoint looks something like:

http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive

Authenticating requests


In our query examples, we generally assume that authentication is disabled in the Server.xml file:

<AuthenticationMethod>none</AuthenticationMethod>
Note: By default, a fresh installation of Wowza Streaming Engine is configured with basic authentication enabled for the REST API. In production environments, we strongly recommend not disabling authentication, as this reflects best practices for security. Each request should include authentication credentials using the -u option in curl. Always ensure that authentication remains enabled and that credentials are protected when working with the REST API.

If you set the authentication method to digest, for example, you'll want to add that to the cURL request as follows:

curl -X [METHOD] \
--digest -u "user:pass" \
[Headers] \
http://[your-wowza-server]:8087/v2/[path-to-resource]

For more information on authenticating API requests, see Change the authentication method for the Wowza Streaming Engine REST API.

Query the REST API using cURL


The Wowza Streaming Engine 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 macOS and Linux, 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.

Note: The curl syntax we use is written for Linux/Unix shells and will work as-is in that environment. On Windows, the syntax differs depending on whether you use Command Prompt (CMD) or Powershell. Be sure to adjust quotation marks and formatting accordingly.

The format for cURL requests to the Wowza Streaming REST API is:

curl -X [METHOD] [Headers] http://[your-wowza-server]:8087/v2/[path-to-resource]

In our query examples, we use line breaks for ease of viewing.

curl -X [METHOD] \
[Headers] \
http://[your-wowza-server]:8087/v2/[path-to-resource]

Headers precede the actual HTTP request. The Wowza Streaming Engine REST API requests in our examples use the Accept, Content-Type, and charset headers as follows:

-H 'Accept:application/json; charset=utf-8'
-H 'Content-Type:application/json; charset=utf-8'

The Accept and Content-Type headers instruct the requests and responses to use JSON syntax. The charset header specifies that the requests and responses use UTF-8 character encoding. The headers can also be specified discretely, as in:

-H 'Accept: application/json' 
-H 'Content-Type: application/json'
-H 'charset: utc-8'

If you prefer to use XML syntax, change the headers to:

-H 'Accept:application/xml; charset=utf-8'
-H 'Content-Type:application/xml; charset=utf-8'

The HTTP method is the action you're requesting of the resource. The Wowza Streaming Engine REST API uses four cURL methods, or commands:

  • GET - Obtain information from the resource.
     
  • PUT - Update information or perform an action on an existing record.
     
  • POST - Create a record.
     
  • DELETE - Remove an existing record.

Parameters and properties can be used to refine the request. They generally correspond to options in the Wowza Streaming Engine Manager.

Query the REST API using PHP


You can wrap the Wowza Streaming Engine REST API with a custom PHP library to configure, manage, and monitor your server through PHP requests. First, download the PHP library from GitHub. Then, point the library to your streaming media server by modifying the following lines in include/constants.php as follows:

define("BASE_DIR", dirname(dirname(__FILE__)));
define("WOWZA_HOST","http://localhost:8087/v2");
define("WOWZA_SERVER_INSTANCE", "serverName");
define("WOWZA_VHOST_INSTANCE", "vhostName");
define("WOWZA_USERNAME", "admin");
define("WOWZA_PASSWORD", "admin");

PHP query examples are available in the tests folder of the Wowza Streaming Engine PHP library download.

More resources