Migrate from v1.6 to v1.7

Migrate from version 1.6 to 1.7


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

A number of things have changed between API versions. While this guide includes most changes you need to know, see the Wowza Video REST API reference documentation to confirm specific details of endpoint behavior in v1.7.

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 Video 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 Video 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.6v1.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 Video 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 Video 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.6v1.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 Video 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 Video 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 Video 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.