Wowza Streaming Cloud REST API migration guide

As you move the codebase 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 how these changes affect your code.

Migrate from version 1.3 to 1.4


Migrating your existing Wowza Streaming Cloud integrations to version 1.4 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 Streaming Cloud 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 Streaming Cloud and Fastly CDN. Because Wowza CDN on Fastly is integrated directly with Wowza Streaming Cloud, 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 Streaming Cloud 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.

v1.3 v1.4
POST /stream_targets/wowza
  • POST /stream_targets/akamai
     
GET /stream_targets/wowza/[stream_target_id]
  • GET /stream_targets/akamai/[stream_target_id]
     
PATCH /stream_targets/wowza/[stream_target_id]
  • PATCH /stream_targets/akamai/[stream_target_id]
DELETE /stream_targets/wowza/[stream_target_id]
  • DELETE /stream_targets/akamai/[stream_target_id]

We also updated object references for Akamai stream targets.

v1.0 v1.3
{
  "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 Streaming Cloud REST API and Protect a Wowza CDN on Fastly stream target with token authentication using the Wowza Streaming Cloud 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 Streaming Cloud 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 Streaming Cloud 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 Streaming Cloud 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.

v1.3 v1.4
GET /usage/stream_sources
  • This endpoint has been sunset and is no longer available.
GET /usage/time/transcoders
  • GET /usage/transcoders
     
GET /usage/storage/peak_recording
  • GET /usage/storage/peak
GET /usage/network/stream_sources
  • This endpoint has been sunset and is no longer available.
GET /usage/network/stream_targets
  • GET /usage/stream_targets
GET /usage/network/transcoders
  • GET /usage/transcoders
GET /usage/viewer_data/stream_targets/[stream_target_id]
  • GET /usage/stream_targets/[stream_target_id]

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

Migrate from version 1.0 to 1.3


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

Versions 1.0, 1.1, and 1.2 have been sunset, so this guide focuses on migrating from v1.0 to v1.3 to include all changes that a user migrating to v1.3 needs to be aware of.

A number of things have changed between API versions. 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.3.

Developer checklist


What's changed


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

Authentication method

In v1.3, we added a more secure authentication method for use in production environments: hash-based message authentication code (HMAC). In this form of authentication, the API key is a private, secret key. It is known to you and the Wowza Streaming Cloud service but never sent directly in an API request. Headers for HMAC include an access key, a timestamp, and a signature generated using the HMAC-256-Hexdigest algorithm. See Authentication to learn how to set this up.

v1.0 v1.3
API key and access key authentication only
curl -X GET \
-H "wsc-api-key: [your API key]" \
-H "wsc-access-key: [your access key]" \
"https://api.cloud.wowza.com/api/[version]/live_streams"
HMAC authentication for production environments
curl -X GET \
-H "wsc-access-key: [your access key]" \
-H "wsc-timestamp: [timestamp]" \
-H "wsc-signature: [code-generated-signature]" \
"https://api.cloud.wowza.com/api/[version]/live_streams"
API key and access key authentication for initial testing of API only
curl -X GET \
-H "wsc-api-key: [your API key]" \
-H "wsc-access-key: [your access key]" \
"https://api.cloud.wowza.com/api/[version]/live_streams"

Retrieving detailed information about individual objects

In v1.3, we reduced the response information returned when you fetch the index of an object. This applies to GET requests for all transcoders, live streams, players, recordings, stream targets, Wowza stream targets, custom stream targets, ultra low latency stream targets, stream sources, and Akamai stream sources. Previously, responses included detailed information about each object. If you need to request detailed information about an object in v1.3, you'll need to fetch the index, then fetch a single object to view its details. See the v1.3 Wowza Streaming Cloud REST API reference documentation to see the specifics for each request.

You can use query parameters to limit the scope of your initial request. See Get paginated query results with the Wowza Streaming Cloud REST API and Get paginated query results with the Wowza Streaming Cloud REST API for information on query parameters.

v1.0 v1.3
A request to an index, for example,
GET /live_streams
returned detailed information about every live stream in the account.  
{
  "live_streams": [
    {
      "aspect_ratio_height": 1080,
      "aspect_ratio_width": 1920,
      "billing_mode": "pay_as_you_go",
      "broadcast_location": "us_west_california",
      "closed_caption_type": "cea",
      "connection_code": "0e15cb",
      ...
      "stream_targets": [],
      "target_delivery_protocol": "hls",
      "transcoder_type": "transcoded",
      "updated_at": "2017-12-27T19:27:16.316Z",
      "video_fallback": false
    },
    {
      "aspect_ratio_height": 1080,
      "aspect_ratio_width": 1920,
      "billing_mode": "twentyfour_seven",
      "broadcast_location": "eu_germany",
      ...
      "stream_targets": [],
      "target_delivery_protocol": "hls-hds",
      "transcoder_type": "passthrough",
      "updated_at": "2017-12-28T11:01:09.316Z",
      "use_stream_source": false,
      "video_fallback": false
    },
    {
      "aspect_ratio_height": 1080,
      "aspect_ratio_width": 1920,
      "billing_mode": "pay_as_you_go",
      "broadcast_location": "us_east_virginia",
      ...
      "stream_targets": [],
      "target_delivery_protocol": "hls-https",
      "transcoder_type": "transcoded",
      "updated_at": "2017-12-28T09:56:49.316Z",
      "use_stream_source": true,
      "video_fallback": false
    },
    ...
  ]
}
A request to an index, for example,
GET /live_streams
returns limited information about every live stream in the account. Responses with over 1000 entries are paginated by default.
{
  "live_streams": [
    {
    "id": "wdjfqvsv",
    "name": "My PAYG Transcoded WSE Stream",
    "created_at": "2019-02-27T16:07:56.139Z",
    "updated_at": "2019-02-28T22:06:54.139Z"
    },
    {
    "id": "kyxwktgq",
    "name": "My 24x7 Passthrough GoCoder Stream",
    "created_at": "2019-02-27T16:07:56.139Z",
    "updated_at": "2019-03-01T09:31:08.139Z"
    },
    {
    "id": "ly40zdsg",
    "name": "My PAYG Transcoded Teradek Stream",
    "created_at": "2019-02-27T16:07:56.139Z",
    "updated_at": "2019-03-01T06:59:49.139Z"
    },
    ...
  ]
}
To retrieve details about a live stream, identify the ID of the live stream and use it in a second request.
GET /live_streams/[live_stream_id]
This returns all available details of a single live stream.
{
  "live_stream": {
    "aspect_ratio_height": 1080,
    "aspect_ratio_width": 1920,
    "billing_mode": "pay_as_you_go",
    "broadcast_location": "us_west_california",
    "closed_caption_type": "cea",
    "connection_code": "0e15cb",
    ...
    "stream_targets": [],
    "target_delivery_protocol": "hls",
    "transcoder_type": "transcoded",
    "updated_at": "2019-01-29T07:45:46.878Z",
    "use_stream_source": true
  }
}

Compare workflows for each updated endpoint:

v1.0 v1.3
GET /live_streams
  • GET /live_streams
  • GET /live_streams/[live_stream_id]
GET /transcoders
  • GET /transcoders
  • GET /transcoders/[transcoder_id]
GET /players
  • GET /players
  • GET /players/[player_id]
GET /recordings
  • GET /recordings
  • GET /recordings/[recordings_id]
GET /transcoders/[transcoder_id]/recordings
  • GET /transcoders/[transcoder_id]/recordings
  • GET /recordings/[recording_id]
GET /stream_sources
  • GET /stream_sources
  • GET /stream_sources/akamai/[stream_source_id]
GET /stream_targets
  • GET /stream_targets
  • GET /stream_targets/custom/[target_id]

    or
  • GET /stream_targets/wowza/[target_id]

    or
  • GET /stream_targets/ull/[target_id]

Stream target endpoint syntax and object references

In v1.3, we've broken out stream targets into three sets of endpoints based on the type of stream target.  Custom targets, Wowza targets, and ultra low latency targets have separate endpoints with corresponding create, retrieve, update, and delete functionality. See the v1.3 Stream Targets section of the API reference documentation for more information.

v1.0 v1.3
POST /stream_targets
  • POST /stream_targets/custom
     
  • POST /stream_targets/wowza
     
  • POST /stream_targets/ull
GET /stream_targets/[target_id]
  • GET /stream_targets/custom/[target_id]
     
  • GET /stream_targets/wowza/[target_id]
     
  • GET /stream_targets/ull/[target_id]
PATCH /stream_targets/[target_id]
  • PATCH /stream_targets/custom/[target_id]
  • PATCH /stream_targets/wowza/[target_id]
  • PATCH /stream_targets/ull/[target_id]
DELETE /stream_targets/[target_id]
  • DELETE /stream_targets/custom/[target_id]
  • DELETE /stream_targets/wowza/[target_id]
  • DELETE /stream_targets/ull/[target_id]

We've also updated object references for custom stream targets, Wowza stream targets, and ultra low latency stream targets. These didn't exist as separate objects in v1.0 because they were part of the stream target object.

v1.0 v1.3
{
  "stream_target": {
    ...
  }
}
  • {
      "stream_target_custom": {
        ...
      }
    }
  • {
      "stream_target_wowza": {
        ...
      }
    }
  • {
      "stream_target_ull": {
        ...
      }
    }

Stream source endpoint syntax and object references

In v1.3, we've updated the endpoint syntax for stream sources to allow for growth with more stream source types. Although functionality remains the same, stream sources from v1.0 are now Akamai stream sources in v1.3.

Important: As of January 16, 2020, Akamai stream sources are no longer functional. Akamai has withdrawn support for this feature. To prevent a disruption of service, you must update existing stream source configurations. For more information, see Remove an Akamai stream source from a live stream or transcoder using the Wowza Streaming Cloud REST API.
v1.0 v1.3
GET /stream_sources/[stream_source_id]
  • GET /stream_sources/akamai/[stream_source_id]
     
DELETE /stream_sources/[stream_source_id]
  • DELETE /stream_sources/akamai/[stream_source_id]

We've also updated object references for Akamai stream sources. 

v1.0 v1.3
{
  "stream_source": {
    ...
  }
}
{
  "stream_source_akamai": {
    ...
  }
}

Pagination

In v1.3, queries to retrieve all live streams, players, recordings, schedules, stream sources, stream targets, and transcoders have pagination enabled by default. There are maximum of 1000 records displayed at one time. We updated default values for pagination query parameters; page defaults to 1, and per_page defaults to 1000. See Get paginated query results with the Wowza Streaming Cloud REST API for more information.

Deprecations

In addition to deprecations related to endpoint syntax changes for stream targets and stream sources, we deprecated the following parameters and operations.

v1.0 (Deprecated) v1.3 (Use instead)
POST /transcoders/[transcoder_id]/outputs/
[output_id]/add_stream_target
POST /transcoders/[transcoder_id]/outputs/
[output_id]/output_stream_targets
DELETE /transcoders/[transcoder_id]/outputs/
[output_id]/remove_stream_target
DELETE /transcoders/[transcoder_id]/outputs/
[output_id]/output_stream_targets/[id]
POST /stream_sources/add POST /stream_sources/akamai
chunk_size parameter for stream targets
  • Use the chunkSize property with
    POST /stream_targets/[stream_target_id]/properties
use_https parameter for stream targets Use the relativePlaylists property with
POST /stream_targets/[stream_target_id]/properties
video_fallback parameter for transcoders and live streams video_fallback was in preview, and there isn't a suggested replacement
transcoding_uptime_id parameter for transcoders, returned when starting, stopping, and fetching the state of a transcoder  Starting, stopping, or fetching a transcoder returns the uptime_id property instead

Added and updated functionality

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

More resources