Migrate from v1.3 to v1.4

A number of things have changed between version 1.3 and 1.4 of the API. 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.4.

What's changed

Over the course of development, we made the following changes to the REST API from version 1.3 to version 1.4. Use the tables to compare workflows and endpoints in v1.3 to v1.4.

Stream targets

In v1.4, we introduced Wowza CDN on Fastly stream targets. We also renamed Wowza CDN on Akamai stream targets endpoints and removed the geo-blocking and token authentication features.

Wowza CDN on Fastly

With Wowza CDN on Fastly, you can reliably scale your streams to reach global audiences of any size using an integration between Wowza Video and Fastly CDN. Because Wowza CDN on Fastly is integrated directly with Wowza Video, you don't need a separate CDN provider subscription. By default, when you create a live stream, Wowza CDN on Fastly stream targets are automatically provisioned as part of the under the hood live stream setup. To learn more about Wowza CDN on Fastly stream targets, see Get started streaming to Wowza CDN on Fastly with the Wowza Video REST API.

Wowza CDN on Akamai

In v1.3, Wowza CDN on Akamai stream targets were referred to as Wowza stream targets. For v1.4, we've updated the naming convention and now refer to Wowza CDN on Akamai stream targets. This change includes renaming the endpoints for creating, fetching, updating, and deleting Akamai stream targets.

We also updated object references for Akamai stream targets.

{
  "stream_target_wowza": {
    ...
  }
}

{
  "stream_target_akamai": {
    ...
  }
}

Lastly, we sunset the /stream_targets/[stream_target_id]/geoblock and stream_targets/[stream_target_id]/token_auth endpoints for Wowza CDN on Akamai stream targets.

Note: You can configure geo-block and token authentication on Fastly stream targets. For more information, see Geo-block Wowza CDN on Fastly stream targets with the Wowza Video REST API and Protect a Wowza CDN on Fastly stream target with token authentication using the Wowza Video REST API.

Stream sources

In v1.4, we introduced Wowza stream sources. We also sunset the Akamai stream sources feature.

Wowza stream sources

Wowza stream sources provide an entry point into Wowza Video that automatically detects the broadcast location of your source encoder or camera and uses the closest ingest point based on a DNS query. A transcoder connected to a Wowza stream source starts automatically when the video source starts and stops automatically when the video source disconnects.

By default, when you create a live stream with a stream source, a Wowza stream source is automatically provisioned as part of the under the hood live stream setup. For more information, see Control a transcoder with a Wowza stream source using the Wowza Video REST API.

Akamai stream sources

Akamai stream sources have been around since v1.0. However, as of January 16, 2020, Akamai no longer supports this feature. As a result, we've removed Akamai stream source functionality from both v1.3 and v1.4. For information on updating existing Akamai stream source configurations, see Remove an Akamai stream source from a live stream or transcoder using the Wowza Video REST API.

Note: You can still retrieve and delete existing Akamai stream sources in v1.3.

Usage endpoint syntax

In v1.4, we made several changes to the usage endpoints for transcoders, stream sources, stream targets, and peak recording storage.

We also added two new endpoints related to transcoders usage:

• To fetch usage (egress) for a specific transcoder, use GET /usage/transcoders/[transcoder_id]
• To fetch a summary of usage (egress) for all transcoders, use GET /usage/transcoders/summary

Delivering streams over HDS

In v1.4, we removed the hls-hds target_delivery_protocol option to create an hds live stream. We also removed the player_hds_playback_url from the response received when creating a live stream. When creating or updating a live stream, the only valid target_delivery_protocol value is now hls-https.

Note: To deliver a stream over HDS, create a transcoder with a Wowza CDN on Akamai stream target that has a provider of akamai.

Recordings

In v1.4, we added new endpoints that allow you to start recording after a transcoder has started and stop recording before a transcoder has stopped.

• To start a recording after a transcoder has started, use
  PUT /transcoders/[transcoder_id]/start_recording
• To stop a recording before a transcoder has stopped, use
  PUT /transcoders/[transcoder_id]/stop_recording

Stream health metrics

In v1.3, we updated the following stream health metrics related to CPU and GPU so that their value returns null and their status returns no_data.

• cpu
• cpu_idle (historic metrics only)
• gpu_decoder_usage
• gpu_driver_version
• gpu_encoder_usage
• gpu_memory_usage
• gpu_usage

In v1.4, we’ve removed these metrics from the response received when querying the following endpoints:

• GET /transcoders/[transcoder_id]/stats
• GET /live_streams/[live_stream_id]/stats
• GET /transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/current
• GET /transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/historic

Added and updated functionality

Check out the other updates and additions to the REST API between v1.3 and v1.4. Links go to the applicable sections of reference documentation unless otherwise noted.

• Added archived and name parameters to the response received when fetching CDN usage for all stream targets or a specific stream target
• Added from and to parameters to the response received when fetching peak recording storage
• Added a restriction to the stream targets and transcoders usage endpoints to limit the maximum number of days that can be queried in a single request to 90 days
• Removed the bytes_billed parameter from the response received when fetching usage (egress) for all transcoders
• Removed the hds_playback_url parameter from the response received when fetching or updating a player