How to Use the REST API for Wowza Streaming Cloud (Video + Tutorial)

August 22, 2018 by

Live-streaming video can be added to any new or existing app or service offering. Whether you’re building a basic broadcasting platform or an interactive experience that involves live user-generated video, such as HQ Trivia, you can use the Wowza Streaming Cloud API to build and manage your live stream.

Learn how in this step-by-step video:

 


We’ve also provided a written step-by-step tutorial documenting the process shown in the video above, which you will find below.

 

Step-by-Step Tutorial: Using the Wowza Streaming Cloud REST API

Time to complete: 30 minutes
Software to Install: Paw

 

In this tutorial, we will look step by step at how to build a and manage a live stream through the API for the following stream actions:

  • Create
  • Start
  • Check Status
  • Stop
  • Delete

Finally, we will use the sandbox, which is recommended when writing your code; you can switch to the live API when you’re ready for deployment.

Now, let’s dive into the tutorial:

1. Navigate to the documentation at https://sandbox.cloud.wowza.com/api/v1.2/docs

2. We will use Paw to build the queries (however, any API testing tool, such as Postman, can be used for this).

3. Let’s first create a new live stream with the API. In Wowza Streaming Cloud, a live stream is a workflow used to build a transcoder up in the cloud, so you can transcode and deliver your content to devices all over the globe.

In Paw, set up the create request. Type in a name for the request in the upper-left field and select POST from the drop-down menu, which is required to create a live stream.

4. The base path for the sandbox is: https://sandbox.cloud.wowza.com

5. The API path is /api/v1.2/

6. On the API documentation page, expand live streams and select Create live stream. You will see all of the required settings toward the top of the list.

7. Scroll to the right, and you will see that this is a post request to the endpoint /live_streams.

8. Back in Paw, enter the complete POST URL to create a live stream:

https://sandbox.cloud.wowza.com/api/v1.2/live_streams

9. Bonus Material (Steps 9-12 are not depicted in the video, but are added here for clarity):
We also need to set up the authentication headers for the request. You will need to grab the API and access keys from https://sandbox.cloud.wowza.com and use these values in the header. To get the API access keys, select the drop-down under your account name and choose API Access.

10. First, copy the API key and then click Add Access Key. Call the Access Key “Demo Sandbox,” or anything else that makes sense for your project. Note that you should see “Running in Sandbox Mode” at the top of the page. (If you do not, make sure you navigated to https://sandbox.cloud.wowza.com).

11. Copy the access key.

12. Back in Paw, add two headers to the request—one for wsc-api-key, and one for wsc-access-key—and paste in the corresponding values from above. Save the Paw session and call it “Wowza API Requests” (and note that if you are using another tool besides Paw, you may need a third header: “Content-Type: application/json”.)

We have now set the request method, request path and the proper authentication headers; at this point, everything is set up to make requests to the API.

13. In order to complete the request, we need to describe it to the live API. We will do this in the body. In this example, the Wowza GoCoder app is the source encoder for the live stream. (There are other encoder options, and they are listed in the API reference documentation under “create a live stream endpoint,” as well as in the technical documentation about broadcasting using the REST API.)

Add this JSON content to the body of the request:

{

 “live_stream”: {

   “name”: “Live Stream Demo”,

   “transcoder_type”: “transcoded”,

   “billing_mode”: “pay_as_you_go”,

   “broadcast_location”: “us_west_california”,

   “recording”: false,

   “encoder”: wowza_gocoder,

   “delivery_method”: “push”,

   “target_delivery_protocol”: “hls”,

   “use_stream_source”: true,

   “aspect_ratio_width”: 1920,

   “aspect_ratio_height”: 1080,

   “player_type”: “original_html5”,

   “player_responsive”: false,

   “player_width”: 640,

   “hosted_page”: false

 }

}

14. Click on the JSON tab and expand.

15. These body parameters are mostly self-explanatory. Refer to the documentation at https://sandbox.cloud.wowza.com/api/v1.2/docs for details. For example, broadcast_location has several options and you have a sample of JSON text to copy from on the right:

16. Back in Paw, let’s execute our request by hitting enter in the Post text box. You should see a 201 Created notification appear, with response information that looks similar to the below. Copy the id value.

17. Next, we need to start the stream. In Paw, right-click on Create Live Stream, select Duplicate and call it “Start Live Stream.” (For Mac computers, mouse settings can be configured to use a right click, since this is not the default).

18. Go back to the documentation and look at the Start a live stream request. Note the id is a required path parameter, and this is a PUT operation using the endpoint /live_streams/{id}/start.

19. Make the corresponding entries back in Paw; then we need to remove the body, as we do not need content to be sent here. Replace the “{id}” with your id, copied in step 16.

20. Execute the request; you will see a 200 OK response back, and the state will show as starting. It can take a few moments to get the transcoder up and running in the cloud.

21. Let’s check the current state of the stream with another API call, using a state endpoint request. Duplicate the Start Live Stream request and call this one “Live Stream State.”

22. Look at the documentation again for Fetch the State of a live stream. This uses GET using the id and /state as the action of the request.

23. In Paw, you should see something similar to the below (the result is 200 OK and the stream has started). Note that you can’t send information from your encoder to the live stream until it has started. We recommend checking to see if the state has changed from “starting” to “started” every five seconds, so as not to overload the API; if you need it quicker, you can check it once every second, but not more frequently than that (sub-second queries are not recommended).

 

24. Next, we will stop the live stream. Stopping a stream is similar to starting a stream, so duplicate Start Live Stream and simply change the /start action to /stop. (You can drag the new stop request down in the Paw list of sessions if you like.) Run it. You should get back a 200 OK and see that it has stopped. Stopping is pretty immediate, so there’s no need to check the state of the request. At this point, you would no longer be billed for using a live stream in non-sandbox mode.

25. Remove the live stream once you are completely done using it. This is important because having too many assets in your account can impact the performance of the API.

Duplicate the Start Live Stream request one more time. Look at the documentation again. Note there is no delete action on the end, but rather, it uses a DELETE method.

26. Go back to Paw, and your request should look like the below. A 204 No Content notification is returned, which indicates that there is no content to represent that stream anymore.

27. Attempt to get the state by running the Live Stream State again, and you will see a result of ERR-410-RecordDeleted.

28. Bonus Material (not covered in the video, but added here for clarity): You can see the test request and the response at the same time with a split-screen, which is the up/down arrow icon highlighted below.

In this tutorial, you learned how to work with a live stream through the use of the REST API for the basic functions of Create, Start, Check Status, Stop and Delete. You also learned how to use the documentation at https://sandbox.cloud.wowza.com/api/v1.2/docs in order to make the request in programs such as Postman or Paw. Now, start building!

Additional Resources

How to Broadcast a Live Stream Using the Wowza Streaming Cloud REST API
How to Use the Wowza Streaming Cloud REST API
Wowza Streaming Cloud REST API Examples