Wowza Streaming Cloud REST API migration guide

Migrating your existing Wowza Streaming Cloud integrations to version 1.7 of the REST API allows 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.7.

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.6/live_streams

      New version: https://api.cloud.wowza.com/api/v1.7/live_streams

What's changed


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

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

Highlights:

  • Set a referer policy with Wowza CDN on Fastly stream targets – Control access to a stream by setting a referer policy that allows or blocks access, depending on the domain that’s requesting (the referer) the access. You can use this functionality to prevent unauthorized websites from hosting a stream you own.
  • Use reference IDs in webhook payloads – You can associate a unique ID, typically from another part of your system or application, with transcoder events and return that ID in transcoder webhook payloads.
  • Access VOD streams using the live playlist URL – By enabling the live2vod property, your viewers can use the same playback URL they used for the live event to view the VOD asset after the stream ends.

Only in v1.7

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

Playback URLs for stream targets
Delivery protocols for stream targets
Referer policies and headers for Fastly stream targets
Geoblocking for Fastly stream targets
Reference IDs for webhooks
Egress for VOD usage
Zones for VOD usage
Advanced properties arrays

Playback URLs for stream targets

In v1.7, we added playback_urls to the requests of following endpoints:

  • POST /stream_targets/custom
  • PATCH /stream_targets/custom/[target_id]

We also added playback_urls to the responses of following endpoints:

  • POST /stream_targets/akamai
  • PATCH /stream_targets/akamai/[target_id]
  • GET /stream_targets/akamai/[target_id]
  • POST /stream_targets/custom
  • PATCH /stream_targets/custom/[target_id]
  • GET /stream_targets/custom/[target_id]

With this change, the following parameters are sunset in the previous endpoints:

  • hds_playback_url - custom and Akamai stream targets
  • hls_playback_url - custom and Akamai stream targets
  • rtmp_playback_url - custom stream targets
Sample request payload
{
  "stream_target_custom": {
    "name": "My Custom Stream Target",
    "playback_urls": {
      "rtmp": "rtmp://cp123456.live.edgefcs.net/live/[EVENT]@654321"
    },
    "primary_url": "rtmp://p.ep123456.i.akamaientrypoint.net/EntryPoint",
    "provider": "rtmp",
    "stream_name": "c8467d50@123456"
  }
}

Delivery protocols for stream targets

In v1.7, we added delivery_protocols to the requests for following endpoints:

  • POST /stream_targets/fastly
  • PATCH /stream_targets/fastly/[target_id]

The default value is hls. The valid values are hls and dash. Use dash to send an MPEG-DASH stream to the target for digital rights management (DRM) use on Google and Microsoft devices. See About digital rights management in Wowza Streaming Cloud for more information.

We also added delivery_protocols to the responses of following endpoints:

  • POST /stream_targets/akamai
  • PATCH /stream_targets/akamai/[target_id]
  • GET /stream_targets/akamai/[target_id]
  • POST /stream_targets/custom
  • PATCH /stream_targets/custom/[target_id]
  • GET /stream_targets/custom/[target_id]
  • POST /stream_targets/fastly
  • PATCH /stream_targets/fastly/[target_id]
  • GET /stream_targets/fastly/[target_id]
  • POST /stream_targets/ull
  • PATCH /stream_targets/ull/[target_id]
  • GET /stream_targets/ull/[target_id]
Sample request payload
{
  "stream_target_fastly": {
    "name": "MyDashTarget",
    "delivery_protocols": [
      "dash"
     ]  
   }
}

Referer policies and headers for Fastly stream targets

In v1.7, we added the following parameters to the requests for the /stream_targets/fastly endpoints:

  • referer_enabled
  • referer_allow_empty
  • referer_policy
  • referer_domains

These parameters allow you to set a referer policy and require a Referer header in order to access a stream through a Wowza CDN on Fastly stream target. Use this functionality to prevent unauthorized websites from hosting a stream you own. See Set referer policy for Wowza CDN on Fastly stream targets with the Wowza Streaming Cloud REST API for more information.

Sample request payload
{
  "stream_target_fastly": {
    "name": "MyHLSTarget",
    "referer_enabled": true,
    "referer_policy": "allow",
    "referer_allow_empty": false,
    "referer_domains": "example.com, example2.com"
   }
}

Geoblocking for Fastly stream targets

In v1.7, we removed all geoblock_[name] properties except geoblock_enabled from the responses of the /stream_targets/fastly endpoints when geoblock_enabled is set to false.

v1.6 v1.7
{
  "stream_target_fastly": {
    "id": "xsvhj6zz",
    "name": "My Fastly Target",
    "state": "activated",
    "stream_name": "L2VlOCsx",
    "playback_urls": {
      "hls": [
        {
          "name": "default",
          "url": "https://cdn3.wowza.com/1/SG9LQTJudlBybE81/L2VlOCsx/hls/live/playlist.m3u8"
        }
      ]
    },
    "force_ssl_playback": false,
    "use_legacy_tls": false,
    "token_auth_enabled": false,
    "token_auth_playlist_only": false,
    "geoblock_enabled": false,
    "geoblock_by_location": "disabled",
    "geoblock_ip_override": "disabled",
    "created_at": "2021-10-14T18:01:35.000Z",
    "updated_at": "2021-10-14T18:01:35.000Z"
  }
}
{
  "stream_target_fastly": {
    "id": "crb1jldz",
    "name": "My Fastly Target",
    "state": "activated",
    "stream_name": "ei96VG9l",
    "delivery_protocols": [
      "hls"
      ],
    "playback_urls": {
      "hls": [
        {
          "name": "default",
          "url": "https://cdn3-qa.wowza.com/1/RWlFTG03a0VMVmJs/ei96VG9l/hls/live/playlist.m3u8"
        }
      ]
    },
    "force_ssl_playback": false,
    "use_legacy_tls": false,
    "token_auth_enabled": false,
    "token_auth_playlist_only": false,
    "geoblock_enabled": false,
    "referer_enabled": false,
    "created_at": "2021-10-14T18:07:18.000Z",
    "updated_at": "2021-10-14T18:07:18.000Z"
  }
}

Reference IDs for webhooks

In v1.7, we added reference_id to the requests for following endpoints:

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

Use reference_id to set a unique ID returned in object_data of transcoder webhook payloads. This is useful if you have an ID in your system or application you want to associate with transcoder events. See Receive Wowza Streaming Cloud event notifications with webhooks for more information.

The default value for reference_id in the webhook payloads is null.

Sample request payload
{
  "transcoder": {
    "billing_mode": "pay_as_you_go",
    "broadcast_location": "us_west_california",
    "buffer_size": 4000,
    "delivery_method": "push",
    "low_latency": true,
    "name": "MyABRtranscoder",
    "protocol": "rtsp",
    "transcoder_type": "transcoded",
    "reference_id": "mySystemID_01"
   } 
} 
Sample transcoder webhook payload
{
  "version": "1.0",
  "event": "stop.complete",
  "event_id": "67360faf-b709-4e2c-a846-1d130f643449",
  "event_time": 1617908933.0713735,
  "object_type": "transcoder",
  "object_id": "y5mfswdy",
  "object_data": {
    "uptime_id": "jbfg6npg",
    "reference_id": "mySystemID_01"
   }
}

Egress for VOD usage

In v1.7, we added the following new endpoints:

  • GET /usage/vod_streams/egress
  • GET /usage/vod_streams/egress/[vod_stream_id]
  • GET /usage/vod_streams/egress/summary

Use these endpoints to fetch VOD egress usage. For VOD streams, egress is the traffic that Wowza CDN on Fastly generates by pulling the VOD asset from storage. See View usage data with the Wowza Streaming Cloud REST API for more information.

Sample response payload
{
  "summary": {
    "bytes": 38246347
  },
  "limits": {
    "from": "2021-10-07T00:00:00.000Z",
    "to": "2021-10-14T00:00:00.000Z"
  }
}

Zones for VOD usage

In v1.7, we removed the zones property from objects in the responses of the following endpoints:

  • GET /usage/vod_streams/[vod_stream_id]
  • GET /usage/vod_streams/summary 
  • GET /usage/vod_streams/[vod_stream_id]/countries
  • GET /usage/vod_streams/[vod_stream_id]/renditions
v1.6 v1.7
{
"summary": {
  "unique_viewers": 6,
  "viewing_time": 1210,
  "bytes": 259873844,
  "zones": [
    {
      "name": "global",
      "type": "fastly",
      "bytes": 259873844.0
    }
  ]
}
{
"summary": {
  "unique_viewers": 24,
  "viewing_time": 700,
  "bytes": 41989033
  }  
}

Advanced properties arrays

In v1.7, we added the ability to set an array of properties from the following endpoints:

  • POST /transcoders/[transcoder_id]/properties
  • POST /stream_targets/fastly
  • PATCH /stream_targets/fastly/[target_id]
  • POST /stream_targets/akamai
  • PATCH /stream_targets/akamai/[target_id]
  • POST /stream_targets/[target_id]/properties

The following endpoints already allowed setting arrays of properties, and the API reference documentation is updated to reflect this:

  • POST /transcoders
  • PATCH /transcoders/[transcoder_id]

See Set advanced properties with the Wowza Streaming Cloud REST API for more information.

Sample request payload
{
  "stream_target_fastly":{
    "name": "My Fastly Target",
    "properties": [
      {
        "key": "chunkSize", 
        "section": "hls", 
        "value": "8"
      },
      {
       "key": "convertAMFData", 
       "section": "hls", 
       "value": true
      }
    ]
  }
} 

In v1.7 and earlier versions

After the release of version 1.6 and during the development of version 1.7, we made the following changes to 1.7 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.7.

Live-to-VOD property

Change present in: v1.5 through v1.7

We added the live2vod transcoder property.

{
  "property": {
    "section": "vod_stream",
    "key": "live2vod",
    "value": true
  }
}

This property allows your viewers to access a VOD stream using the same playback URL they used to view the original stream. When enabled, Wowza Streaming Cloud replaces the live playlist with the VOD playlist after the stream ends. Viewers can watch the VOD stream without modifying the URL the player used for the live stream.

Upgrade from older versions


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