• Application management query examples 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. This article demonstrates ways to create and manage applications in a Wowza Streaming Engine instance using some basic cURL examples to query the Wowza Streaming Engine REST service. For a complete breakdown and documentation of the API, see How to access documentation for the Wowza Streaming Engine REST API.

    Note: Wowza Streaming Engine 4.3.0 or later is required. You must also have working knowledge of cURL and REST-related services.

    Contents


    Get a list of applications
    Create a new application
    Update application settings
    Add custom properties to an application
    Restart an application

    Get a list of applications


    The following example shows how to get a list of all the applications on a given Wowza Streaming Engine media server:
    curl -X GET --header 'Accept:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications
    An example result:
    {"restURI":"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications","applications":[{"id":"live","href":"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live","appType":"Live","dvrEnabled":false,"drmEnabled":false,"transcoderEnabled":false},{"id":"vod","href":"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/vod","appType":"VOD","dvrEnabled":false,"drmEnabled":false,"transcoderEnabled":false}]}

    Create a new application


    Creating a new application can be a little more involved depending on what you're looking to change from the default configuration. These examples demonstrate how to create an application with the default configuration, and then expand upon that example to include additional configuration options.

    The following example shows how to create an application (testlive) with the default configuration and a stream type of live:
    curl -X POST --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive -d'
    {
       "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive",
       "name": "testlive",
       "appType": "Live",
       "clientStreamReadAccess": "*",
       "clientStreamWriteAccess": "*",
       "description": "Testing our Rest Service",
       "streamConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/streamconfiguration",
          "streamType": "live"
       }
    }'
    An example result:
    {"success":true,"message":"Application (testlive) created successfully."}
    The complexity of creating an application depends on the configuration options you want to enable/add upon creation. The next example creates the default application (testlive), and adds security on published streams (similar to Require password authentication for RTMP):
    curl -X POST --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive -d'
    {
       "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive",
       "name": "testlive",
       "appType": "Live",
       "description": "Testing our Rest Service",
       "streamConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/streamconfiguration",
          "streamType": "live"
       },
       "securityConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/security",
          "secureTokenVersion": 0,
          "clientStreamWriteAccess": "*",
          "publishRequirePassword": true,
          "publishPasswordFile": "",
          "publishRTMPSecureURL": "",
          "publishIPBlackList": "",
          "publishIPWhiteList": "",
          "publishBlockDuplicateStreamNames": false,
          "publishValidEncoders": "",
          "publishAuthenticationMethod": "digest",
          "playMaximumConnections": 0,
          "playRequireSecureConnection": false,
          "secureTokenSharedSecret": "",
          "secureTokenUseTEAForRTMP": false,
          "secureTokenIncludeClientIPInHash": false,
          "secureTokenHashAlgorithm": "",
          "secureTokenQueryParametersPrefix": "",
          "secureTokenOriginSharedSecret": "",
          "playIPBlackList": "",
          "playIPWhiteList": "",
          "playAuthenticationMethod": "none"
       },
       "modules": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/modules",
          "moduleList": [
             {
                "order": 0,
                "name": "base",
                "description": "Base",
                "class": "com.wowza.wms.module.ModuleCore"
             },
             {
                "order": 1,
                "name": "logging",
                "description": "Client Logging",
                "class": "com.wowza.wms.module.ModuleClientLogging"
             },
             {
                "order": 2,
                "name": "flvplayback",
                "description": "FLVPlayback",
                "class": "com.wowza.wms.module.ModuleFLVPlayback"
             },
             {
                "order": 3,
                "name": "ModuleCoreSecurity",
                "description": "Core Security Module for Applications",
                "class": "com.wowza.wms.security.ModuleCoreSecurity"
             }
          ]
       }
    }'
    As you can see, some additional information is required to make that happen. In this case, securityConfig (to include the publishRequirePassword option) and moduleList (to add ModuleCoreSecurity) were added.

    The following example shows how to create the default application (livetest) with the packetizers for your live stream and security for published streams configuration options:
    curl -X POST --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive -d'
    {
       "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive",
       "name": "testlive",
       "appType": "Live",
       "description": "Testing our Rest Service",
       "streamConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/streamconfiguration",
          "streamType": "live",
         "liveStreamPacketizer": [
             "cupertinostreamingpacketizer",
             "smoothstreamingpacketizer",
             "sanjosestreamingpacketizer"
          ]
       },
       "securityConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/security",
          "secureTokenVersion": 0,
          "clientStreamWriteAccess": "*",
          "publishRequirePassword": true,
          "publishPasswordFile": "",
          "publishRTMPSecureURL": "",
          "publishIPBlackList": "",
          "publishIPWhiteList": "",
          "publishBlockDuplicateStreamNames": false,
          "publishValidEncoders": "",
          "publishAuthenticationMethod": "digest",
          "playMaximumConnections": 0,
          "playRequireSecureConnection": false,
          "secureTokenSharedSecret": "",
          "secureTokenUseTEAForRTMP": false,
          "secureTokenIncludeClientIPInHash": false,
          "secureTokenHashAlgorithm": "",
          "secureTokenQueryParametersPrefix": "",
          "secureTokenOriginSharedSecret": "",
          "playIPBlackList": "",
          "playIPWhiteList": "",
          "playAuthenticationMethod": "none"
       },
       "modules": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/modules",
          "moduleList": [
             {
                "order": 0,
                "name": "base",
                "description": "Base",
                "class": "com.wowza.wms.module.ModuleCore"
             },
             {
                "order": 1,
                "name": "logging",
                "description": "Client Logging",
                "class": "com.wowza.wms.module.ModuleClientLogging"
             },
             {
                "order": 2,
                "name": "flvplayback",
                "description": "FLVPlayback",
                "class": "com.wowza.wms.module.ModuleFLVPlayback"
             },
             {
                "order": 3,
                "name": "ModuleCoreSecurity",
                "description": "Core Security Module for Applications",
                "class": "com.wowza.wms.security.ModuleCoreSecurity"
             }
          ]
       }
    }'
    The result should show a new configuration that includes the three packetizers listed under the streamConfig/liveStreamPacketizer key in the request above.

    Finally, here's an example of a request to create an application that includes all of the configuration options:
    curl -X POST --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive -d'
    {
       "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive",
       "version": "1425058151000",
       "name": "testlive",
       "appType": "Live",
       "description": "Default application for testlive streaming created when Wowza Streaming Engine is installed. Use this application with its default configuration or modify the configuration as needed. You can also copy it to create another testlive application.",
       "applicationTimeout": 0,
       "pingTimeout": 0,
       "repeaterQueryString": "",
       "clientStreamReadAccess": "*",
       "clientStreamWriteAccess": "*",
       "avSyncMethod": "senderreport",
       "httpStreamers": [
          "cupertinostreaming",
          "smoothstreaming",
          "sanjosestreaming",
          "mpegdashstreaming"
       ],
       "mediaReaderRandomAccessReaderClass": "",
       "httpOptimizeFileReads": false,
       "mediaReaderBufferSeekIO": false,
       "captionLiveIngestType": "",
       "vodTimedTextProviders": [
          "vodcaptionprovidermp4_3gpp"
       ],
       "securityConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/security",
          "secureTokenVersion": 0,
          "clientStreamWriteAccess": "*",
          "publishRequirePassword": true,
          "publishPasswordFile": "",
          "publishRTMPSecureURL": "",
          "publishIPBlackList": "",
          "publishIPWhiteList": "",
          "publishBlockDuplicateStreamNames": false,
          "publishValidEncoders": "",
          "publishAuthenticationMethod": "digest",
          "playMaximumConnections": 0,
          "playRequireSecureConnection": false,
          "secureTokenSharedSecret": "",
          "secureTokenUseTEAForRTMP": false,
          "secureTokenIncludeClientIPInHash": false,
          "secureTokenHashAlgorithm": "",
          "secureTokenQueryParametersPrefix": "",
          "secureTokenOriginSharedSecret": "",
          "playIPBlackList": "",
          "playIPWhiteList": "",
          "playAuthenticationMethod": "none"
       },
       "streamConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/streamconfiguration",
          "streamType": "live",
          "storageDir": "${com.wowza.wms.context.VHostConfigHome}/content",
          "createStorageDir": false,
          "storageDirExists": true,
          "keyDir": "${com.wowza.wms.context.VHostConfigHome}/keys",
          "testliveStreamPacketizer": [
             "cupertinostreamingpacketizer",
             "smoothstreamingpacketizer",
             "sanjosestreamingpacketizer",
             "mpegdashstreamingpacketizer"
          ],
          "httpRandomizeMediaName": false
       },
       "dvrConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/dvr",
          "licenseType": "Monthly",
          "inUse": true,
          "dvrEnable": false,
          "windowDuration": 0,
          "storageDir": "${com.wowza.wms.context.VHostConfigHome}/dvr",
          "archiveStrategy": "append",
          "dvrOnlyStreaming": false,
          "startRecordingOnStartup": true,
          "dvrEncryptionSharedSecret": "",
          "dvrMediaCacheEnabled": false,
          "httpRandomizeMediaName": false
       },
       "drmConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/drm",
          "licenseType": "Monthly",
          "inUse": false,
          "cupertinoEncryptionAPIBased": false,
          "ezDRMUsername": "",
          "ezDRMPassword": "",
          "buyDRMUserKey": "",
          "buyDRMProtectSmoothStreaming": false,
          "buyDRMProtectCupertinoStreaming": false,
          "buyDRMProtectMpegDashStreaming": false,
          "verimatrixProtectCupertinoStreaming": false,
          "verimatrixCupertinoKeyServerIpAddress": "",
          "verimatrixCupertinoKeyServerPort": 0,
          "verimatrixCupertinoVODPerSessionKeys": false,
          "verimatrixProtectSmoothStreaming": false,
          "verimatrixSmoothKeyServerIpAddress": "",
          "verimatrixSmoothKeyServerPort": 0
       },
       "transcoderConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/transcoder",
          "available": true,
          "licensed": true,
          "licenses": -1,
          "licensesInUse": 0,
          "templates": {
             "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/transcoder/templates",
             "templates": [
                {
                   "id": "transcode",
                   "href": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/transcoder/templates/transcode"
                },
                {
                   "id": "audioonly",
                   "href": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/transcoder/templates/audioonly"
                },
                {
                   "id": "transcode-h265-divx",
                   "href": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/transcoder/templates/transcode-h265-divx"
                },
                {
                   "id": "transrate",
                   "href": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/transcoder/templates/transrate"
                }
             ]
          },
          "templatesInUse": "${SourceStreamName}.xml,transrate.xml",
          "profileDir": "${com.wowza.wms.context.VHostConfigHome}/transcoder/profiles",
          "templateDir": "${com.wowza.wms.context.VHostConfigHome}/transcoder/templates",
          "createTemplateDir": false
       },
       "modules": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/modules",
          "moduleList": [
             {
                "order": 0,
                "name": "base",
                "description": "Base",
                "class": "com.wowza.wms.module.ModuleCore"
             },
             {
                "order": 1,
                "name": "logging",
                "description": "Client Logging",
                "class": "com.wowza.wms.module.ModuleClientLogging"
             },
             {
                "order": 2,
                "name": "flvplayback",
                "description": "FLVPlayback",
                "class": "com.wowza.wms.module.ModuleFLVPlayback"
             },
             {
                "order": 3,
                "name": "ModuleCoreSecurity",
                "description": "Core Security Module for Applications",
                "class": "com.wowza.wms.security.ModuleCoreSecurity"
             }
          ]
       }
    }'

    Update application settings


    The following example shows a way to update the packetizer setting to include MPEG-DASH:
    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive -d'
    {
      "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive",
      "name":"testlive",
       "streamConfig": {
          "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/streamconfiguration",
          "streamType": "live",
          "liveStreamPacketizer": [
             "cupertinostreamingpacketizer",
             "smoothstreamingpacketizer",
             "sanjosestreamingpacketizer",
             "mpegdashstreamingpacketizer"
          ]
       }
    }'
    The expected result:
    {"success":true,"message":"Saved"}
    You can make modifications to the other properties in a similar fashion. All configuration options are included in the last Create a new application example request.

    Add custom properties to an application


    To add custom properties to this configuration, you can use the following request:
    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/adv -d'
    {
       "restURI": "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/adv",
       "version": "1430682096000",
       "modules": [
          {
             "order": 0,
             "name": "base",
             "description": "Base",
             "class": "com.wowza.wms.module.ModuleCore"
          },
          {
             "order": 0,
             "name": "logging",
             "description": "Client Logging",
             "class": "com.wowza.wms.module.ModuleClientLogging"
          },
          {
             "order": 0,
             "name": "flvplayback",
             "description": "FLVPlayback",
             "class": "com.wowza.wms.module.ModuleFLVPlayback"
          },
          {
             "order": 0,
             "name": "ModuleDRMVerimatrix",
             "description": "ModuleDRMVerimatrix",
             "class": "com.wowza.wms.drm.module.verimatrix.ModuleDRMVerimatrix"
          },
          {
             "order": 0,
             "name": "ModuleDRMBuyDRM",
             "description": "ModuleDRMBuyDRM",
             "class": "com.wowza.wms.drm.module.buydrm.ModuleDRMBuyDRM"
          },
          {
             "order": 0,
             "name": "ModulePushPublish",
             "description": "Module Push Publish",
             "class": "com.wowza.wms.pushpublish.module.ModulePushPublish"
          },
          {
             "order": 0,
             "name": "MyCustomModule",
             "description": "Module Custom Module",
             "class": "com.my.custom.path.MyCustomModule"
          }
       ],
       "advancedSettings": [
          {
             "enabled": false,
             "canRemove": true,
             "name": "debugAACTimecodes",
             "value": "false",
             "defaultValue": "false",
             "type": "Boolean",
             "sectionName": "cupertinostreamingpacketizer",
             "section": "/Root/Application/LiveStreamPacketizer",
             "documented": true
          },
          {
             "enabled": false,
             "canRemove": true,
             "name": "debugMP3Timecodes",
             "value": "false",
             "defaultValue": "false",
             "type": "Boolean",
             "sectionName": "cupertinostreamingpacketizer",
             "section": "/Root/Application/LiveStreamPacketizer",
             "documented": true
          },
          {
             "enabled": false,
             "canRemove": true,
             "name": "cupertinoChunkDurationTarget",
             "value": "0",
             "defaultValue": "10000",
             "type": "Integer",
             "sectionName": "cupertinostreamingpacketizer",
             "section": "/Root/Application/LiveStreamPacketizer",
             "documented": true
          },
          {
             "enabled": true,
             "canRemove": false,
             "name": "myCustomPropertyName",
             "value": "myValue",
             "defaultValue": null,
             "type": "String",
             "sectionName": "Application",
             "section": "/Root/Application",
             "documented": false
          }
       ]
    }'
    This modifies your application's configuration to include the custom modules and properties:
    <Modules>
    	<Module>
    		<Name>base</Name>
    		<Description>Base</Description>
    		<Class>com.wowza.wms.module.ModuleCore</Class>
    	</Module>
    	<Module>
    		<Name>logging</Name>
    		<Description>Client Logging</Description>
    		<Class>com.wowza.wms.module.ModuleClientLogging</Class>
    	</Module>
    	<Module>
    		<Name>flvplayback</Name>
    		<Description>FLVPlayback</Description>
    		<Class>com.wowza.wms.module.ModuleFLVPlayback</Class>
    	</Module>
    	<Module>
    		<Name>ModuleDRMVerimatrix</Name>
    		<Description>ModuleDRMVerimatrix</Description>
    		<Class>com.wowza.wms.drm.module.verimatrix.ModuleDRMVerimatrix</Class>
    	</Module>
    	<Module>
    		<Name>ModuleDRMBuyDRM</Name>
    		<Description>ModuleDRMBuyDRM</Description>
    		<Class>com.wowza.wms.drm.module.buydrm.ModuleDRMBuyDRM</Class>
    	</Module>
    	<Module>
    		<Name>ModulePushPublish</Name>
    		<Description>Module Push Publish</Description>
    		<Class>com.wowza.wms.pushpublish.module.ModulePushPublish</Class>
    	</Module>
    	<Module>
    		<Name>MyCustomModule</Name>
    		<Description>Module Custom Module</Description>
    		<Class>com.my.custom.path.MyCustomModule</Class>
    	</Module>
    </Modules>
    <!-- Properties defined here will be added to the IApplication.getProperties() and IApplicationInstance.getProperties() collections -->
    <Properties>
    	<Property>
    		<Name>myCustomPropertyName</Name>
    		<Value>myValue</Value>
    		<Type>String</Type>
    	</Property>
    </Properties>

    Restart an application


    To restart an application, you can use the following request:
    curl -X PUT --header 'Accept:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/actions/restart

    Originally Published: 06-16-2015.
    Updated: For Wowza Streaming Engine 4.3.0 on 10-06-2015.

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