Wowza Streaming Cloud REST API migration guide

Migrating your existing Wowza Streaming Cloud integrations to version 1.6 of the REST API will allow you to take advantage of new features and performance improvements.

As you move the code base for your streaming workflow from one version of the Wowza Streaming Cloud™ REST API to a later version, use this guide to track what's changed and understand how these changes affect your code. While this guide includes most changes you need to know, see the Wowza Streaming Cloud REST API reference documentation to confirm specific details of endpoint behavior in v1.6.

Migration checklist

  • Review deprecations to determine whether your code uses deprecated endpoints or parameters.
  • Review added and updated functionality to determine whether you want to make use of new parameters or parameter values.
  • Update your code:
    • For changes to operations and objects, as necessary.
    • To reflect the new base URL for calls to the API. For example:
      Previous version: https://api.cloud.wowza.com/api/v1.5/live_streams
      New version: https://api.cloud.wowza.com/api/v1.6/live_streams

What's changed


This topic covers REST API changes that occurred between the release of v1.5 and v1.6. These changes fall into two categories:

  • Changes present only in v1.6.
  • Changes that originate from the development of v1.6, but also retroactively apply to earlier versions of the API. These are non-breaking changes unless otherwise communicated by Wowza.

Highlights:

  • Wowza CDN on Akamai usage data – Previously, v1.3 was the most recent REST API version to return Akamai stream target data in the /usage/stream_targets endpoints. Now you can upgrade from v1.3 to any newer version of the API and have Akamai data returned.
  • WebRTC playback – You can ingest and playback WebRTC streams for low latency, near real time delivery of streams.

Only in v1.6

Over the course of development, we made the following changes to the REST API from v1.5 to v1.6. These changes are present in v1.6 only.

Direct playback URLs
Audio and video codecs
Ingest IP whitelist
Playback stream name
File names for recordings

Direct playback URLs

In v1.6, we replaced playback_url with playback_urls in the response for the following endpoints:

  • POST /stream_targets/fastly
  • GET /stream_targets/fastly/[target_id]
  • PATCH /stream_targets/fastly/[target_id]
v1.5 v1.6
{
   "playback_url": "https://[wowzasubdomain].wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8"
}
{
  "playback_urls": {
    "hls": [
      {
        "name": "default",
        "url": "https://[wowzasubdomain].wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8"
      }    
    ]
  }
}

Audio and video codecs

In v1.6, we added functionality that allows you to specify audio and video codecs, from a limited set of options, for output renditions in the transcoder workflow. The following is the full list of options for the audio_codec and video_codec parameters:

  • audio_codec
    • aac – Transcodes the audio to AAC. AAC is the most commonly compatible audio codec for protocols.
    • opus – Transcodes the audio to Opus. Opus is used for WebRTC streams.
    • passthrough – Sends the stream to the target without transcoding the audio data.
    • disabled – Sends the stream to the target without an audio track.
  • video_codec
    • h264 – Transcodes the video to H.264. H.264 is the most commonly compatible video codec for protocols.
    • passthrough – Sends the stream to the target without transcoding the video track.
    • disabled – Sends the stream to the target without a video track.

The audio_codec and video_codec parameters replace the stream_format, passthrough_audio, and passthrough_video parameters in the following endpoints:

  • POST /transcoders/[transcoder_id]/outputs
  • GET /transcoders/[transcoder_id]/outputs
  • GET /transcoders/[transcoder_id]/outputs/[id]
  • PATCH /transcoders/[transcoder_id]/outputs/[id]
v1.5 v1.6
{
  "output": {
    "stream_format": "audiovideo",
    "aspect_ratio_height": 480,
    "aspect_ratio_width": 848,
    "bitrate_audio": 128,
    "bitrate_video": 1600,
    "framerate_reduction": "1/2",
    "h264_profile": "main",
    "keyframes": "follow_source"
    "passthrough_audio": false,
    "passhtrough_video": false
  }
}
{
  "output": {
    "video_codec": "h264",
    "audio_codec": "aac",
    "aspect_ratio_height": 480,
    "aspect_ratio_width": 848,
    "bitrate_audio": 128,
    "bitrate_video": 1600,
    "framerate_reduction": "1/2",
    "h264_profile": "main",
    "keyframes": "follow_source"
  }
}

Ingest IP whitelist

In v1.6, we renamed the ingest_ip_whitelist parameter to ingest_ip_allowlist in the following endpoints:

  • POST /stream_targets/ull
  • GET /stream_targets/ull/[id]
  • PATCH /stream_targets/ull/[id]

Playback stream name

In v1.6, we added playback_stream_name to the responses for the following endpoints:

  • POST /live_streams
  • GET /live_streams/[id]
  • PATCH /live_streams/[id]
  • POST /transcoders
  • GET /transcoders/[id]
  • PATCH /transcoders/[id]
"playback_stream_name": "wxyz6789"

File names for recordings

In v1.6, we added the file_name parameter to the response for the GET /recordings endpoint.

"file_name": "31a4f9f4.stream.0.mp4"

In v1.6 and earlier versions

After the release of version 1.5 and during the development of version 1.6, we made the following changes to 1.6 that also retroactively change earlier versions of the API. You might already be aware of these changes as they've been released and the changes communicated through the Wowza Streaming Cloud REST API release notes, but you might still consider them as you upgrade to version 1.6.

Wowza CDN on Akamai usage data
WebRTC playback
Passthrough for WebRTC live streams
Stream a file
Access Control: Allow Origin property
Direct playback connection limit
Format of direct playback URL names
Application name length
Current viewer data updates
Maximum value for playlistSeconds
Outputs per transcoder

Wowza CDN on Akamai usage data

Change present in: v1.4 through v1.6

We added usage data for Wowza CDN on Akamai stream targets to the following endpoints:

  • /usage/stream_targets
  • /usage/stream_targets/summary
  • /usage/stream_targets/[id]
  • /usage/stream_targets/[id]/countries
  • /usage/stream_targets/[id]/renditions
Important: Previously, v1.3 was the most recent REST API version to return Akamai stream target data in the /usage/stream_targets endpoints. This change allows customers who remained on v1.3 for the Akamai data to upgrade to a newer version of the REST API and retain the ability to retrieve that data.

WebRTC playback

Change present in: v1.3 through v1.6

We added functionality to the Wowza Streaming Cloud REST API that allows you to deliver WebRTC streams for playback directly from the transcoder. You can do direct playback using the /live_streams or /transcoders endpoints. See WebRTC workflows in Wowza Streaming Cloud to learn more about WebRTC and the workflows you can choose from.

Passthrough for WebRTC live streams

Change present in: v1.3 through v1.6

We removed passthrough as a transcoder_type for WebRTC streams created through the /live_streams endpoint.

Stream a file

Change present in: v1.5 and v1.6

We removed the file value from the delivery_method parameter for the following endpoints:

  • POST /live_streams
  • GET /live_streams/[live_stream_id]
  • PATCH /live_streams/[live_stream_id]
  • POST /transcoders
  • GET /transcoders/[transcoder_id]
  • PATCH /transcoders/[transcoder_id]

To create a live stream that uses a file as the source, you need to set the following values:

  • Live stream workflow: Set encoder to file, delivery_method to pull, and source_url to the URL where the file is located.
  • Transcoder workflow: Set protocol to file, delivery_method to pull, and source_url to the URL where the file is located.
Note: Existing live streams that use a file as the source were automatically updated to the new configuration. No further action is required.

Live stream workflow

v1.4 v1.5 and v1.6
{
   "live_stream": {
     "aspect_ratio_height": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "file",
     "encoder": "file",
     "hosted_page": true,
     "hosted_page_sharing_icons": true,
     "name": "MyLiveStream",
     "player_responsive": true,
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   }
}
{
   "live_stream": {
     "aspect_ratio_height": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "pull",
     "encoder": "file",
     "hosted_page": true,
     "hosted_page_sharing_icons": true,
     "name": "MyLiveStream",
     "player_responsive": true,
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   }
}

Transcoder workflow

v1.4 v1.5 and v1.6
{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "file",
     "name": "MyTranscoder",
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   } 
}
{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "pull",
     "name": "MyTranscoder",
     "protocol": "file",
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   } 
}

For more information, see Stream a file with the Wowza Streaming Cloud REST API.

Access Control: Allow Origin property

Change present in: v1.3 through v1.6

We added the acoa property for Wowza CDN on Fastly stream targets so you can explicitly specify the origin that can access the stream. While most streams won't need the origin explicitly set, you might use this property for older players that don't send the Referer header in their stream request. For more information, see Configure a property for a stream target.

"properties": [
      {
        "key": "acao",
        "section": "hls",
        "value": "http://<origin>"
      }
    ] 

Direct playback connection limit

Change present in: v1.3 through v1.6

We changed the maximum value for the play_maximum_connections parameter from 100 to the maximum number of connections the specific transcoder can support. Generally, adaptive bitrate transcoders are larger and support more viewer connections (up to 300) while passthrough transcoders are smaller and support fewer viewer connections.

Format of direct playback URL names

Change present in: v1.3 through v1.6

We changed the format of the name object in direct_playback_urls to display the video and audio bitrate values for the output rendition.

Previous v1.3 through v1.6
"direct_playback_urls": {
  - "rtmp": [
      ...
      - {
        "name": "1280x720",
        "output_id": "0g116zkf",
        "url": "rtmp://abc123.entrypoint.cloud.wowza.com/app-B8P6K226/wxyz6789_stream2"
        }
       ...
  }
"direct_playback_urls": {
  - "rtmp": [
      ...
      - {
        "name": "V:1280x720+A:128K",
        "output_id": "0g116zkf",
        "url": "rtmp://abc123.entrypoint.cloud.wowza.com/app-B8P6K226/wxyz6789_stream2"
        }
       ...
  }

Application name length

Change present in: v1.5 and v1.6

We updated the transcoder application_name property to default to names that are eight characters in length instead of four.

v1.4 v1.5 and v1.6
"application_name": "app-3757"
"application_name": "app-B8P6K226"

Current viewer data updates

Change present in: v1.4 through v1.6

We changed how often current viewer data is updated from 90 seconds to 5 minutes. Previously, unique_views would occasionally show the number of current viewers as 0.

Maximum value for playlistSeconds

Change present in: v1.3 through v1.6

We changed the maximum valid value for the stream target property, playlistSeconds, from 200 seconds to 28800 seconds (8 hours).

Outputs per transcoder

Change present in: v1.3 through v1.6

We adjusted transcoder functionality to allow only 10 output renditions per transcoder. Existing transcoders with more than 10 outputs retain those outputs, but you can't add more. For the best playback performance, we recommend limiting the outputs on a single transcoder to 8 or fewer.

Upgrade from older versions

This topic covers REST API changes that occurred between the release of version 1.5 and version 1.6. If you are upgrading from a version earlier than version 1.5, also review all other other API changes that apply to your migration: