Migrate from v1.8 to v1.9

Updated on 03/15/2023 10:31 am PDT

Migrate from version 1.8 to 1.9

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

A number of things have changed between version 1.8 and 1.9 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.9.

What's changed

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

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

Highlights:

  • Added new functionality to Real-Time Streaming at Scale, making it even easier to scale to global audiences. You can record streams, specify broadcast regions, and view usage data!
  • v1.9 uses JSON Web Token-based authentication. See Authentication for more information.

Only in v1.9

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

New endpoints
Updated endpoints
General updates

New endpoints

In v1.9, we added the following new endpoints. 

  • GET /usage/real_time_streams — View usage data via API from Wowza Video for a real-time stream or streams over a given time period. Returns all the real-time streams. Optionally you can send multiple parameters:
    • "from": The start of the range of time you want to view.
    • "to": The end of the range of time you want to view.
    • "next_page_key": Returns a paginated view of results from the HTTP request.
    • "per_page": Indicates how many records should be included in a page of results.
Request Response 
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ${WV_JWT}" \ 
 -X "GET" \
  "${WV_HOST}/api/${WV_VERSION}/usage/real_time_streams?from=2022-04-07&to=2022-04-11"
 
{
    "real_time_streams": [
        {
            "id": "03m4bmjp",
            "name": "test"
            "bytes_in": 16696434,
            "bytes_out": 16694201
        }
    ],
    "pagination": {
        "payload_version": 2.0,
        "total_records": 1427,
        "next_page_key": "rgyyxvjf",
        "per_page": 1000,
        "total_pages": 2
    },
    "limits": {
        "from": "2022-07-25T00:00:00.000Z",
        "to": "2022-08-17T00:00:00.000Z"
    }
}
  • GET /usage/real_time_stream/{id} — View usage data via API from Wowza Video for the stream associated with the id. Optionally you can send multiple parameters:
    • "from": The start of the range of time you want to view.
    • "to": The end of the range of time you want to view.
Request Response 
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ${WV_JWT}" \ 
 -X "GET" \
  "${WV_HOST}/api/${WV_VERSION}/usage/real_time_stream/{id}?from=2022-04-07&to=2022-04-11"
 
{
    "real_time_stream": {
        "id": "03m4bo1o",
        "name": "test",
        "bytes_in": 1890231,
        "bytes_out": 829102
    },
    "limits": {
        "from": "2022-07-25T00:00:00.000Z",
        "to": "2022-08-17T00:00:00.000Z"
    }
}

Updated endpoints

While developing v1.9 of the API, we made changes to the following endpoints:

Assets
Assets

Removed null values from the following asset endpoints:

  • GET /assets/ID — The fields returned vary depending on when you send this request. For example, if a resource hasn't been created yet during the processing state, you won't see available_renditions in the response. We also added upload_url to the response of this request when the state of the asset is uploading. If your original upload URL expired and you need a new one for an asset, send this request and the response will contain a new upload URL.
  • PATCH /assets/ID — The fields returned vary depending on when you send this request. For example, if a stream doesn't have unique viewer data, you won't see unique_viewers in the response.
     
    Note: Assets must be uploaded and complete processing before they can be updated.
v1.8 response v1.9 response 
{
  "asset": {
    "id": "i4qsbwvi",
    "name": "My Asset",
    "created_at": "2022-06-30T18:02:20.000Z",
    "updated_at": "2022-06-30T18:02:20.000Z",
    "playback_enabled": false,
    "thumbnail_url": null,
    "state": "uploading",
    "processing_percentage": 0.0
    "file_size": 0,
    "playback_url": null,
    "download_url": null,
    "file_name": "MyAsset.mp4",
    "description": "null",
    "available_renditions": null,
    "duration": 0,
    "tags": [],
    "unique_viewers": null,
    "total_viewing_time": null,
    "average_view_time": 0,
    "total_storage_size": 0,
    "vod_stream_id": "null"
    "recording_id": "l8qsbwvu"
  }
}
 
{
  "asset": {
    "id": "i4qsbwvi",
    "name": "My Asset",
    "created_at": "2022-06-30T18:02:20.000Z",
    "updated_at": "2022-06-30T18:02:20.000Z",
	"playback_enabled": false,
    "file_size": 0,
    "duration": 0,
    "state": "uploading",
    "processing_percentage": 0.0,
    "file_name": "MyAsset.mp4",
    "tags": [],
    "upload_url": "https://storage.googleapis.com/qa-wse-recordings/uploads/recording_crjpxqjx/MyAsset.mp4...",
    "average_view_time": 0,
    "total_storage_size": 0,
    "recording_id": "l8qsbwvu"
  }
}
v1.8 response v1.9 response 
  {
    "asset": {
        "id": "zokkttsy",
        "name": "MyAsset.mp4",
        "created_at": "2022-08-25T23:17:20.979Z",
        "updated_at": "2022-08-25T23:33:54.481Z",
        "playback_enabled": false,
        "thumbnail_url": null,
        "state": "processing",
        "processing_percentage": 0.0,
        "file_size": 60,
        "playback_url": null,
        "download_url": "https://storage.googleapis.com/prod-wse-recordings/WS1FjZh9/recording_g5r2pbz1/MyAsset.mp4",
        "file_name": "MyAsset.mp4",
        "description": null,
        "available_renditions": null,
        "duration": 9241,
        "tags": [],
        "unique_viewers": null,
        "total_viewing_time": null,
        "average_view_time": 0,
        "total_storage_size": null,
        "vod_stream_id": null,
        "recording_id": "g5r2pbz1"
    }
}
 
{
  "asset": {
    "id": "i4qsbwvi",
    "name": "My Asset",
    "tags": [
      "Tag1",
      "Tag2",
      "Tag3"
    ],
    "recording_id": "l8qsbwvu",
    "state": "processing",
    "created_at": "2021-06-30T18:02:20.000Z",
    "updated_at": "2021-06-30T18:02:20.000Z",
    "download_url": "https://storage.googleapis.com/qa-wse-recordings/zjpfl9f7/recording_xcwvfkgy/MyAsset.mp4",
    "file_size": 2372820,
    "duration": 9241,
    "average_view_time": 12580,
    "file_name": "MyAsset.mp4",
    "processing_percentage": 100
  }
}
v1.8 response v1.9 response 
 {
    "asset": {
        "id": "zokkttsy",
        "name": "MyAsset.mp4",
        "created_at": "2022-08-25T23:17:20.979Z",
        "updated_at": "2022-08-25T23:33:54.481Z",
        "playback_enabled": false,
        "thumbnail_url": null,
        "state": "failed",
        "processing_percentage": 0.0,
        "file_size": 60,
        "playback_url": null,
        "download_url": "https://storage.googleapis.com/prod-wse-recordings/WS1FjZh9/recording_g5r2pbz1/MyAsset.mp4",
        "file_name": "MyAsset.mp4",
        "description": null,
        "available_renditions": null,
        "duration": 9241,
        "tags": [],
        "unique_viewers": null,
        "total_viewing_time": null,
        "average_view_time": 0,
        "total_storage_size": null,
        "vod_stream_id": null,
        "recording_id": "g5r2pbz1"
    }
}
 
{
  "asset": {
    "id": "i4qsbwvi",
    "name": "My Asset",
    "tags": [
      "Tag1",
      "Tag2",
      "Tag3"
    ],
    "recording_id": "l8qsbwvu",
    "state": "failed",
    "created_at": "2021-06-30T18:02:20.000Z",
    "updated_at": "2021-06-30T18:02:20.000Z",
    "average_view_time": 12580,
    "file_name": "MyAsset.mp4",
    "processing_percentage": 100
  }
}
  • Changed DELETE /assets/ID so you can now delete an asset in the uploading state in addition to the complete and failed states. You can't delete an asset in the processing state.
Stream Targets
Real-time streams

Regions

Added a region parameter so you can specify a distribution region closest to your broadcast location. The valid values are emea and americas. Previously existing streams default to americas.

v1.8 
 v1.9  
POST /real_time
{
"real_time_stream": {
"name": "MyRealTimeStream"
}
}
 
Response 
{
"real_time_stream": {
"id": "rpfm75cv",
"name": "MyRealTimeStream",
"stream_name": "b46967b60bcc4c13be3b1e121df512ca",
"token": "e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"rtmp_url": "rtmp://rtmp-realtime2.wowza.com/v2/pub/b46967b60bcc4c13be3b1e121df512ca?token=e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"enable_secure_viewer": false,
"state": "active",
"created_at": "2022-08-04T18:03:56.000Z",
"updated_at": "2022-08-04T18:03:56.000Z"
}
}
 
POST /real_time
{
"real_time_stream": {
"name": "MyRealTimeStream",
"region": "emea"
}
}
 
Response
{
"real_time_stream": {
"id": "rpfm75cv",
"name": "MyRealTimeStream",
"stream_name": "b46967b60bcc4c13be3b1e121df512ca",
"token": "e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"rtmp_url": "rtmp://rtmp-realtime2.wowza.com/v2/pub/b46967b60bcc4c13be3b1e121df512ca?token=e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"enable_secure_viewer": false,
"state": "active",
"created_at": "2022-08-04T18:03:56.000Z",
"updated_at": "2022-08-04T18:03:56.000Z",
"region": "emea"
}
}

  • GET /real_time - Returns all real-time streams with their region shown. 
v1.8 response v1.9 response
 
{
        "real_time_stream": {
        "id": "2adffc17",
        "name": "MyRealTimeStream",
        "stream_name": "8d304b93f1684320a54f2798666eeca7",
        "token": "97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc",
        "rtmp_url": "rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/8d304b93f1684320a54f2798666eeca7?token=97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc",
        "enable_secure_viewer": false,
        "state": "active",
        "created_at": "2021-06-30T18:02:20.000Z",
        "updated_at": "2021-06-30T20:03:16.000Z"
        }
}
 
{
"real_time_streams": [
"id": "dhlwpgny",
"name": "Isabella real time stream 1",
"state": "active",
"created_at": "2021-07-29T17:08:26.000Z",
"updated_at": "2021-07-29T17:08:26.000Z",
"region": "americas"
},
{
"id": "lltf6sb1",
"name": "Andy postman",
"state": "active",
"created_at": "2021-07-29T17:10:46.000Z",
"updated_at": "2021-07-29T17:10:46.000Z",
"region": "americas"
},
v1.8 response v1.9 response
 
 {
        "real_time_stream": {
        "id": "3fdf83gk",
        "name": "Mac Avantage Test",
        "stream_name": "0695b892ce874a8a85058a2ee8d2925b",
        "token": "17d47baf95d41ebb5b819bd11fdd6bd49b2fd1486cc8f03efd568629ba81f4c4",
        "rtmp_url": "rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/0695b892ce874a8a85058a2ee8d2925b?token=17d47baf95d41ebb5b819bd11fdd6bd49b2fd1486cc8f03efd568629ba81f4c4",
        "enable_secure_viewer": false,
        "state": "active",
        "created_at": "2022-09-13T19:24:05.000Z",
        "updated_at": "2022-09-13T19:24:05.000Z",
        }
    }
 
 {
        "real_time_stream": {
        "id": "3fdf83gk",
        "name": "Mac Avantage Test",
        "stream_name": "0695b892ce874a8a85058a2ee8d2925b",
        "token": "17d47baf95d41ebb5b819bd11fdd6bd49b2fd1486cc8f03efd568629ba81f4c4",
        "rtmp_url": "rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/0695b892ce874a8a85058a2ee8d2925b?token=17d47baf95d41ebb5b819bd11fdd6bd49b2fd1486cc8f03efd568629ba81f4c4",
        "enable_secure_viewer": false,
        "state": "active",
        "created_at": "2022-09-13T19:24:05.000Z",
        "updated_at": "2022-09-13T19:24:05.000Z",
        "region": "americas"
    }

Recording

Added a recording parameter which allows you to create a recording from a real-time stream. This has to be done when creating the real-time stream using POST. 

Note: You can't update this value after you create the stream.
  • POST /real_time - Can set the recording parameter to true to create a recording from a real-time stream.
v1.8 
 v1.9  
POST /real_time
{
"real_time_stream": {
"name": "MyRealTimeStream"
}
}
 
Response 
{
"real_time_stream": {
"id": "rpfm75cv",
"name": "MyRealTimeStream",
"stream_name": "b46967b60bcc4c13be3b1e121df512ca",
"token": "e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"rtmp_url": "rtmp://rtmp-realtime2.wowza.com/v2/pub/b46967b60bcc4c13be3b1e121df512ca?token=e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"enable_secure_viewer": false,
"state": "active",
"created_at": "2022-08-04T18:03:56.000Z",
"updated_at": "2022-08-04T18:03:56.000Z"
}
}
 
POST /real_time
{
"real_time_stream": {
"name": "MyRealTimeStream",
"recording": true
}
}
 
Response
{
"real_time_stream": {
"id": "rpfm75cv",
"name": "MyRealTimeStream",
"stream_name": "b46967b60bcc4c13be3b1e121df512ca",
"token": "e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"rtmp_url": "rtmp://rtmp-realtime2.wowza.com/v2/pub/b46967b60bcc4c13be3b1e121df512ca?token=e06eaad4ce7ca1b736355c54171061cb7ec4ae6b3ead400e87dc5205f3624d60",
"enable_secure_viewer": false,
"state": "active",
"created_at": "2022-08-04T18:03:56.000Z",
"updated_at": "2022-08-04T18:03:56.000Z",
"recording": true
}
}

In v1.9 and earlier versions

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

  • We removed the ability to create Wowza CDN on Akamai stream targets.
Wowza CDN on Akamai stream targets

You can no longer create Wowza CDN on Akamai stream targets. You can still create a custom target that uses Akamai as a third-party CDN. While you can view details of an Akamai stream and delete it, that functionality will also soon be disabled.

As part of the Wowza CDN on Akamai deprecation, the following endpoints and parameters/values are removed or changed:

Live stream delivery_type
  • POST /live_stream — The parameter delivery_type has been deprecated. For Wowza Video a stream can only be single-bitrate.  

General updates

We added the following feature updates that don't change existing requests or responses but might be helpful to consider when upgrading your integration with Wowza Video.

  • Wowza Video transitioned to a JSON Web Token-based authentication scheme, rather than an API key/access key scheme. JWT-based authentication is now the only authentication method in v1.9 and later.
  • Changed player embed codes and hosted pages to use video in the URL for new and updated players, instead of cloud. Existing URLs that use cloud will continue to work and are redirected to the Video URL.
  • Updated the way filtering works for the /ASSET endpoint. See Get filtered query results with the Wowza Video REST API for more information.
  • Fixed an issue where POST/assets returned a 200 OK status instead of a 201 Created status.
  • We'll be replacing the existing IP addresses for Wowza CDN on Fastly stream targets. While the change hasn't gone into effect yet, if you stream directly to Wowza CDN from Wowza Streaming Engine, you should add these IP addresses to your firewall rules so your integration continues to work seamlessly when the change occurs. 
    • 129.153.100.158
    • 129.153.114.13
    • 129.154.207.194
    • 132.145.253.238
    • 138.3.255.30
    • 141.147.1.186
    • 146.56.156.1
    • 158.101.43.210
    • 193.123.241.42

© 2007–2024 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status