• How to access documentation for the Wowza Streaming Engine REST API

    Wowza Streaming Engine™ media server software has a REST Application Programming Interface (API) that can be used to configure, manage, and monitor the media server through HTTP requests. Wowza Streaming Engine has a servlet that provides access to runtime documentation of the REST API. The documentation is displayed as JSON data in a Swagger user interface (v1.2) in a static webpage. You can use Try it out! buttons for the REST API endpoints in the Swagger UI to control the Wowza Streaming Engine software. This article describes how to access the REST API documentation.

    Important:
    • Wowza Streaming Engine software version 4.3.0 or later is required. If you were previously given access to the REST API technology in older Wowza Streaming Engine software versions, please update your Wowza Streaming Engine installation.

    • A separate REST API license is NOT required to use the REST API technology. You can use your regular Subscription or Perpetual license for the Streaming Engine software.
    Notes:

    Contents


    Installation
    Configuration
    HTTP headers for the REST API responses
    More resources

    Installation


    If you installed Wowza Streaming Engine 4.3.0 (or later) using an Installer, your software installation has the properties needed to configure access to the REST API documentation. Proceed to the Configuration section.

    If you updated your Wowza Streaming Engine software to version 4.3.0 (or later) using a ZIP file, your software installation might not have the properties needed to configure access to the REST API documentation. Open the [install-dir]/conf/Server.xml file in a text editor and add the following properties to the <Server>/<RESTInterface> section:
    <DocumentationServerEnable>false</DocumentationServerEnable>
    <DocumentationServerPort>8089</DocumentationServerPort>
    <!-- none, basic, digest-->
    <DocumentationServerAuthenticationMethod>digest</DocumentationServerAuthenticationMethod>
    Note: These properties are built-in with Wowza Streaming Engine 4.1.0 and later. You don't need to add these properties if you updated your Wowza Streaming Engine 4.1.0 software installation to version 4.3.0 (or later).

    Configuration


    The REST API documentation is turned off in a default Wowza Streaming Engine installation. After you enable the documentation output, you can open a static webpage in a browser to view the documentation in a more readable form. This article includes a link to the compressed (zipped) folder that has the static webpage and related resources. The Wowza Streaming Engine software requires additional configuration to allow the webpage to access the documentation.

    Enable the Wowza Streaming Engine REST API documentation servlet

    The REST API documentation is turned off in a default Wowza Streaming Engine installation. Use the following procedure to enable REST API documentation output so you can view it:

    1. On the computer that has the Wowza Streaming Engine software installed, open the [install-dir]/conf/Server.xml file in a text editor and change:
      <DocumentationServerEnable>false</DocumentationServerEnable>
      to:
      <DocumentationServerEnable>true</DocumentationServerEnable>
    2. (Optional) To change the default documentation servlet port, change:
      <DocumentationServerPort>8089</DocumentationServerPort>
      to:
      <DocumentationServerPort>[port-number]</DocumentationServerPort>
    3. Restart the Wowza media server.

    View the REST API documentation

    Wowza provides a static webpage and related resources in a compressed (zipped) folder that you can use to view the REST API documentation in a more readable form. You must configure the Wowza Streaming Engine software to allow the webpage to access the documentation servlet.

    1. On the computer that has the Wowza Streaming Engine software installed, open the [install-dir]/conf/Server.xml file in a text editor.

    2. Change the <RESTInterface>/<DocumentationServerAuthenticationMethod> property from:
      <DocumentationServerAuthenticationMethod>digest</DocumentationServerAuthenticationMethod>
      to:
      DocumentationServerAuthenticationMethod>none</DocumentationServerAuthenticationMethod>
      Important: This setting turns off the authentication requirement for the documentation servlet to let the static webpage access the REST API documentation. For this reason, we recommend that the Wowza Streaming Engine instance be hosted in a closed test environment (not exposed to external networks or to the Internet).
    3. In the <RESTInterface>/<Properties> section, add the restUserHTTPHeaders property to enable cross-origin resource sharing (CORS).
      Note: If you're running Wowza Streaming Engine 4.5.0 (or later), skip this step. CORS headers are enabled by default on the REST interface in these software versions.
      <Property>
          <Name>restUserHTTPHeaders</Name>
          <Value>Access-Control-Allow-Origin:*|Access-Control-Allow-Methods:OPTIONS,GET,PUT,DELETE,POST|Access-Control-Allow-Headers:Content-Type</Value>
      </Property>
      For detailed instructions on how to add this custom property, see HTTP headers for the REST API responses.

    4. (Optional) Change the <RESTInterface>/<AuthenticationMethod> property from:
      <AuthenticationMethod>digest</AuthenticationMethod>
      to:
      <AuthenticationMethod>none</AuthenticationMethod>
      Important: This setting turns off the authentication requirement for the Wowza Streaming Engine REST interface so that you can use the Try it out! button for each REST API endpoint in the static webpage to manage the media server. For this reason, we recommend that the Wowza Streaming Engine instance be hosted in a closed test environment (not exposed to external networks or to the Internet).
    5. Restart the Wowza media server.

    6. Download the compressed (zipped) folder that has the static web page and related resources. Download RESTAPIDocumentationWebpage.zip.

    7. Extract the zipped folder contents (you can extract the contents to any location on your computer, including the desktop), and then open the static webpage [package-root]/index.html in a web browser.

    8. In the upper-right corner of the index.html webpage, enter the URL of the Wowza Streaming Engine server that has the REST API documentation servlet enabled:
      http://[wowza-ip-address]:8089/api-docs
      Note: By default, the webpage tries to access the REST API documentation using http://localhost:8089/api-docs. To access a remote Wowza Streaming Engine server that has the REST API documentation servlet enabled, do the following:

      1. On the Wowza Streaming Engine computer that has the REST API documentation you want to view, open [install-dir]/conf/Server.xml in a text editor, and then add the remote computer's IP address to the <RESTInterface>/<IPWhiteList> property. For details on configuring the <IPWhiteList> property, see Connect to remote Streaming Engine from local Streaming Engine Manager.

      2. Restart the Wowza media server to apply the change.

      3. On the remote computer, in the index.html webpage, enter the URL of the Wowza Streaming Engine server that has the REST API that you want to view in the following format:
        http://[wowza-ip-address]:8089/api-docs
    9. Click Explore.

    HTTP headers for the REST API responses


    You can add the restUserHTTPHeaders property to your server configuration to enable HTTP headers to be added to REST response messages from Wowza Streaming Engine. The property value is a list of HTTP header:value pairs delimited by the pipe (|) character:
    <Property>
    	<Name>restUserHTTPHeaders</Name>
    	<Value>header1:value1|header2:value2A,value2B|header3:value3</Value>
    </Property>
    You can add the restUserHTTPHeaders property and CORS header values to your Server.xml file in Wowza Streaming Engine Manager or by using a text editor.

    To add the restUserHTTPHeaders property in Streaming Engine Manager


    1. In Wowza Streaming Engine Manager, click the Server tab, and then click Server Setup in the contents pane.

    2. In the Server Setup page, click the Properties tab and then click Custom in the Quick Links bar.

      Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
    3. In the Custom area, click Edit. Then click Add Custom Property and specify the following settings in the Add Custom Property dialog box:

      • Path - /Root/Server/RESTInterface

      • Name - restUserHTTPHeaders

      • Type - String

      • Value - Enter any combination of desired CORS HTTP header header:value pairs in a pipe-delimited list. For details and examples, see Configure CORS header properties.

    4. Click Add, then click Save, and then restart the Wowza media server.

    To add the restUserHTTPHeaders property in XML


    1. Open the Server.xml file in a text editor and add the restUserHTTPHeaders property to the <RESTInterface>/<Properties> section in the file:
      <RESTInterface>
      	<Properties>
      		<Property>
      			<Name>restUserHTTPHeaders</Name>
      			<Value>header1:value1|header2:value2A,value2B|header3:value3</Value>
      		</Property>
      	</Properties>
      </RESTInterface>
      For details and examples, see Configure CORS header properties.

    2. Restart the Wowza media server.

    Configure CORS header properties

    Note: If you're running Wowza Streaming Engine 4.5.0 (or later), CORS headers are enabled by default on the REST interface.
    To enable cross-origin resource sharing (CORS) for specific domains foo.example and bar.test, add:
    <Properties>
    	<Property>
    		<Name>restUserHTTPHeaders</Name>
    		<Value>Access-Control-Allow-Origin:http://foo.example,http://bar.test</Value>
    	</Property>
    </Properties>
    By default, CORS only allows the GET, HEAD, and POST request methods. To enable all Wowza Streaming Engine REST API request methods, add the CORS Access-Control-Allow-Methods header:
    <Properties>
    	<Property>
    		<Name>restUserHTTPHeaders</Name>
    		<Value>Access-Control-Allow-Origin:http://foo.example,http://bar.test|Access-Control-Allow-Methods:OPTIONS,GET,PUT,DELETE,POST</Value>
    	</Property>
    </Properties>
    To allow the browser to access specific REST API headers, add the CORS Access-Control-Allow-Headers header:
    <Properties>
    	<Property>
    		<Name>restUserHTTPHeaders</Name>
    		<Value>Access-Control-Allow-Origin:http://foo.example,http://bar.test|Access-Control-Allow-Methods:OPTIONS,GET,PUT,DELETE,POST| Access-Control-Allow-Headers:Content-Type,My-Custom-Header</Value>
    	</Property>
    </Properties>
    The restUserHTTPHeaders property value can have a custom HTTP header. For example, to add My-Custom-Header to the REST API response:
    <Properties>
    	<Property>
    		<Name>restUserHTTPHeaders</Name>
    		<Value>My-Custom-Header:HeaderValue</Value>
    	</Property>
    </Properties>

    More resources


    How to access Wowza Streaming Engine Swagger Documentation with Swagger CodeGen

    How to access Wowza Streaming Engine Swagger Documentation with Chrome Postman

    Originally Published: For Wowza Streaming Engine 4.2.0 on 06-16-2015.
    Updated: For Wowza Streaming Engine 4.5.0 on 06-23-2016.

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