Migrating your existing Wowza Video integrations to version 1.10 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 Video™ 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 Video REST API reference documentation to confirm specific details of endpoint behavior in v1.10.
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:
- To use JSON Web Token-based authentication, rather than an API key/access key, if you're upgrading from v1.8 or earlier. The following table shows what authentication schemes our API versions support.
API Version Authentication Support 1.7 API key + access key, HMAC 1.8 API key + access key, HMAC, JWT 1.9 and later JWT See Authentication to learn how to get a JWT.
- 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.video.wowza.com/api/v1.9/live_streams
New version: https://api.video.wowza.com/api/v1.10/live_streams
- To use JSON Web Token-based authentication, rather than an API key/access key, if you're upgrading from v1.8 or earlier. The following table shows what authentication schemes our API versions support.
What's changed
This topic covers REST API changes that occurred between the release of v1.9 and v1.10. These changes fall into two categories:
- Changes present only in v1.10.
- Changes that originate from the development of v1.10, but also retroactively apply to earlier versions of the API. These are non-breaking changes unless otherwise communicated by Wowza.
Highlights:
- Added the filtering parameter to the GET /assets endpoints.
- Added functionality to create only an MP4 when you record a real-time stream.
Only in v1.10
Over the course of development, we made the following changes to the REST API from v1.9 to v1.10. These changes are present in v1.10 only.
Updated endpoints
While developing v1.10 of the API, we made changes to the following endpoints:
Assets
- Added the filter parameter to the GET /assets endpoints. Previously, these endpoints only supported the query parameter.
Examples- Filter — https://api.video.wowza.com/api/beta/assets?filter[0][field]=created_at&filter[0][gte]=2021-07-14T17:47:45.000Z
- Query — https://api.video.wowza.com/api/beta/assets?sort_direction=desc&sort_column=created_at&per_page=30&state=completed&query=sample
See Get filtered query results with the Wowza Video REST API for more information.
- Updated DELETE /assets/{id} to allow for deleting assets in the processing state. Previously, you could only delete an asset in the uploading, failed, or completed state. When an asset is deleted, any related recordings and VOD streams are removed.
Live Streams
We've changed the request and response format for configuring the hosted page and the player. This change groups the configuration options for each object together in a more structured way.
|
v1.9
|
v1.10 |
|---|---|
POST /live_streams
{
"live_stream": {
"name": "MyLiveStream"
...
"hosted_page": true,
"hosted_page_title": "MyLiveHostedPage",
"hosted_page_description": "This is my hosted page.",
"hosted_page_logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"hosted_page_sharing_icons": true,
...
"player_countdown": true,
"player_countdown_at": "2020-02-01T17:00:00.000Z.",
"player_logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"player_logo_position": "top-left",
"player_responsive": true,
"player_type": "wowza_flowplayer",
"player_video_poster_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"player_width": 640,
...
}
}
Response
{
"live_stream": {
"name": "MyLiveStream"
...
"hosted_page": true,
"hosted_page_title": "MyLiveHostedPage",
"hosted_page_description": "This is my hosted page.",
"hosted_page_logo_image_url": "https://prod.s3.amazonaws.com/uploads/player/hosted_page_logo_image/23424/5bad28.jpg",
"hosted_page_sharing_icons": true,
"hosted_page_url": " "https://player.video.wowza.com/hosted/e8dk5bf6/player.html"",
...
"player_countdown": true,
"player_countdown_at": "2020-02-01T17:00:00.000Z.",
"player_embed_code": "null",
"player_hls_playback_url": "https://wowzasubdomain.wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8",
"player_id": "kwb6pwnv ",
"player_logo_image_url": "https://prod.s3.amazonaws.com/uploads/player/logo_image/23424/5bad28.jpg",
"player_logo_position": "top-left",
"player_responsive": true,
"player_type": "wowza_flowplayer",
"player_video_poster_image_url": "https://prod.s3.amazonaws.com/uploads/player/video_poster_image/23424/5bad28.jpg",
"player_width": 640,
...
}
}
|
POST /live_streams
{
"live_stream": {
"name": "MyLiveStream"
...
"hosted_page": {
"enabled": true,
"page_title": "MyLiveHostedPage",
"description": "This is my hosted page.",
"logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"sharing_icons": true
}
...
"player": {
"countdown": true,
"countdown_at": "2020-02-01T17:00:00.000Z.",
"logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"logo_position": "top-left",
"responsive": true,
"type": "wowza_flowplayer",
"video_poster_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"width": 640
}
...
}
}
Response
{
"live_stream": {
"name": "MyLiveStream"
...
"hosted_page": {
"enabled":true,
"title": "MyLiveHostedPage",
"description": "This is my hosted page.",
"logo_image_url": "https://prod.s3.amazonaws.com/uploads/player/hosted_page_logo_image/23424/5bad28.jpg",
"sharing_icons": true,
"page_url": " "https://player.video.wowza.com/hosted/e8dk5bf6/player.html""
}
...
"player": {
"countdown": true,
"countdown_at": "2020-02-01T17:00:00.000Z.",
"embed_code": "null",
"hls_playback_url": "https://wowzasubdomain.wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8",
"id": "kwb6pwnv ",
"logo_image_url": "https://prod.s3.amazonaws.com/uploads/player/logo_image/23424/5bad28.jpg",
"logo_position": "top-left",
"responsive": true,
"type": "wowza_flowplayer",
"video_poster_image_url": "https://prod.s3.amazonaws.com/uploads/player/video_poster_image/23424/5bad28.jpg",
"width": 640
}
...
}
}
|
Player
We've changed the request and response format for configuring the hosted page. This change groups the configuration options together in a more structured way.
|
v1.9
|
v1.10 |
|---|---|
PATCH /players
{
"player": {
"hosted_page": true,
"hosted_page_title": "MyLiveHostedPage",
"hosted_page_description": "This is my hosted page.",
"hosted_page_logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"hosted_page_sharing_icons": true,
...
"responsive": true,
}
}
Response
{
"player": {
"id": "e8dk5bf6 "
...
"hosted_page": true,
"hosted_page_title": "MyLiveHostedPage",
"hosted_page_description": "This is my hosted page.",
"hosted_page_logo_image_url": "https://prod.s3.amazonaws.com/uploads/player/hosted_page_logo_image/23424/5bad28.jpg",
"hosted_page_sharing_icons": true,
"hosted_page_url": " "https://player.video.wowza.com/hosted/e8dk5bf6/player.html"",
...
"player_responsive": true,
...
}
}
|
PATCH /players
{
"player": {
"hosted_page": {
"enabled": true,
"page_title": "MyLiveHostedPage",
"description": "This is my hosted page.",
"logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]",
"sharing_icons": true
}
...
"responsive": true,
...
}
}
Response
{
"player": {
"id": "e8dk5bf6 "
...
"hosted_page": {
"enabled":true,
"title": "MyLiveHostedPage",
"description": "This is my hosted page.",
"logo_image_url": "https://prod.s3.amazonaws.com/uploads/player/hosted_page_logo_image/23424/5bad28.jpg",
"sharing_icons": true,
"page_url": " "https://player.video.wowza.com/hosted/e8dk5bf6/player.html""
}
...
"responsive": true,
...
}
}
|
Real-time streams
This change impacts Wowza Video subscribers only. You're a Wowza Video subscriber if you have access to Asset Management and Historic and Live Analytics in the user interface.
When you record a real-time stream, an MP4 file and an HLS stream for video-on-demand (VOD) replay are created. VOD streams can take a bit of processing time as multiple renditions are created. If you only need the MP4, you can save processing time by setting disable_vod_encoder to true on POST /real_time.
|
v1.9
|
v1.10 |
|---|---|
POST /real_time
{
"real_time_stream": {
"name": "MyRealTimeStream",
"recording": true
}
}
Response
{
"real_time_stream": {
"id": "2adffc17",
"name": "MyRealTimeStream",
"stream_name": "8d304b93f1684320a54f2798666eeca7v,
"token": "97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc",
"rtmp_url": "rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/8d304b93f1684320a54f2798666eeca7?token=97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc",
"enable_secure_viewer": false,
"state": "active",
"region": "emea",
"recording": true,
"created_at": "2021-06-30T18:02:20.000Z",
"updated_at": "2021-06-30T20:03:16.000Z"
}
}
|
POST /real_time
{
"real_time_stream": {
"name": "MyRealTimeStream",
"recording": true,
"disable_vod_encoder": true
}
}
Response
{
"real_time_stream": {
"id": "2adffc17",
"name": "MyRealTimeStream",
"stream_name": "8d304b93f1684320a54f2798666eeca7v,
"token": "97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc",
"rtmp_url": "rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/8d304b93f1684320a54f2798666eeca7?token=97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc",
"enable_secure_viewer": false,
"state": "active",
"region": "emea",
"recording": true,
"disable_vod_encoder": true,
"created_at": "2021-06-30T18:02:20.000Z",
"updated_at": "2021-06-30T20:03:16.000Z"
}
}
|
In v1.10 and earlier versions
After the release of version 1.10 and during the development of version 1.10, we made the following changes to 1.10 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.10.
Wowza Flowplayer is default player for new live streams
Change present in: v1.7 through v1.10
This change impacts Wowza Video subscribers only. You're a Wowza Video subscriber if you have access to Asset Management and Historic and Live Analytics in the user interface.
Wowza Flowplayer is the default player for new live streams. To support this, the following changes were made:
- Added wowza_flowplayer as the default value to type in the player object for the following /live_streams endpoints:
- POST /live_streams
- GET /live_streams/{id}
- PATCH /live_streams/{id}
- Added wowza_flowplayer as the default value to type for the following /players endpoints:
- GET /players
- GET /players/{id}
- PATCH /players/{id}
If you're a Wowza Video subscriber, you can update an existing live stream's player to wowza_flowplayer, but won't be able to change it later because Wowza Flowplayer is the only option if you are a subscriber.
Removed regions from GET /real_time
Change present in: v1.9 through v1.10
Removed
|
Original
|
Updated |
|---|---|
{
"real_time_streams": [
{
"id": "2adffc17",
"name": "MyRealTimeStream",
"state": "active",
"region": "emea",
"created_at": "2021-01-29T17:16:21.849Z",
"updated_at": "2021-01-31T16:06:47.849Z"
},
{
"id": "if7le8ip",
"name": "MyRealTimeStream2",
"state": "active",
"region": "americas",
"created_at": "2020-01-29T17:16:21.849Zv,
"updated_at": "2020-01-31T02:26:05.849Z"
},
{
"id": "dd4udt1b",
"name": "MyRealTimeStream3",
"state": "active",
"region": "americas",
"created_at": "2020-01-29T17:16:21.849Z",
"updated_at": "2020-01-30T18:13:18.849Z"
}
]
}
|
{
"real_time_streams": [
{
"id": "2adffc17",
"name": "MyRealTimeStream",
"state": "active",
"created_at": "2021-01-29T17:16:21.849Z",
"updated_at": "2021-01-31T16:06:47.849Z"
},
{
"id": "if7le8ip",
"name": "MyRealTimeStream2",
"state": "active",
"created_at": "2020-01-29T17:16:21.849Zv,
"updated_at": "2020-01-31T02:26:05.849Z"
},
{
"id": "dd4udt1b",
"name": "MyRealTimeStream3",
"state": "active",
"created_at": "2020-01-29T17:16:21.849Z",
"updated_at": "2020-01-30T18:13:18.849Z"
}
]
}
|
Changed the value of a video codec in /transcoders
Change present in: v1.7 through v1.10
A value for video_codec returned in the following endpoints is changed from avc1 to h264:
- GET /transcoders/{transcoder_id}/uptimes/{id}/metrics/current
- GET /transcoders/{transcoder_id}/stats
|
Original
|
Updated |
|---|---|
"video_codec": {
"value": "H264",
"status": "normal",
"text": "",
"units": ""
}
|
"video_codec": {
"value": "acv1",
"status": "normal",
"text": "",
"units": ""
}
|
Upgrade from older versions
This topic covers REST API changes that occurred between the release of version 1.9 and version 1.10. If you are upgrading from a version earlier than version 1.9, also review all other API changes that apply to your migration:
