Prefetch Video with Webhooks

The traditional HTTP request/response model is that you the server waits for you to make a request, it does something while you wait for it to return something. This is straight-forward and works well in most situations. This article is going to be about a situation where this may not be optimal.

If you are requesting a lot of videos, or video that hasn't been uploaded to the cloud yet, you may want to skip the waiting involved in the traditional request/response model. You can do this by requesting the video and then asking the server to notify you when it has a response for you. This allows you to queue up a list of videos. You no longer need to keep each connection open waiting on a response.

Think about this as ordreing from a fast food resturant vs hot dog cart. At a fast food place, you put in your order at a cash register and they give you a number. When your food is ready they call that number and you can pick up your food. At a hot dog cart, there is only one guy running it so you order with him, wait for him to make the food, he gives you the food and then you pay. During the lunch rush the fast food resturant is much more efficient and can handle a much higher number of customers.

Using what we learned from the fast food place, we want get the same effiency gains. We do this through Webhooks. Webhooks are the pattern of leaving a URL for a server to POST to when it is ready. In our case we require a Webhook to call when the request has succeeded and optional a webhook to call if the request fails. In both cases we will give you a block of JSON data. You will need to be able to handle receiving a POST request to the specified Webhook URLs.

Step 1: Login

The first step in working with our API is to login with your username, password and API key. All requests to our API should include the API key that you created. After the Authentication step, you will get a token which you will then need to pass into the Authorization step. We automatically return you the user information for the user who just logged-in.

After successfully completing the login process you will get a session cookie to use on all calls during the remainder of your session. Note: you can change the cookie experation length as a user account setting.

Step 2: Get Devices

The currently logged-in user is able to get information about what devices they have been given access to. In the linked example webapp, we display them all and let you choose from the list.

Step 3: Get List of Videos

The Get List of Videos API call will return information about all of the videos for the specified camera between the timestamps provided. This is from the metadata that the bridge has sent to the cloud. This doesn't neccessarily mean it is in the cloud yet.

Step 4: Make the requests

Using the pre-fetch API is similar to retrieving a video. The difference is that you need to supply a URL for the `success_hook` to call when the video has been successfully uploaded. There is also a `failure_hook` that is optional and it will be called if the video upload was not successful. An example failure case could be if the bridge has been unplugged and is not able to upload data. Another failure situation would be if the video requested is out of the retention period.

Unlike most of our examples, to run this example you will need a publically accessable URL to receive the success_hook. This makes it a little bit harder to experiment with this example.

You will make the request as outlined in the prefetch video documentation.

Please be aware that this call may trigger an on-demand upload from the bridge. If the video is not yet in the cloud it will be prioritized immediately and uploaded. This is exactly what we are asking it to do. Please keep in mind that doing a large ammount of videos simultaniously may use all the avialable bandwidth. Care should be used not to negatively impact the site where the bridge is connected.

I have released a full working demo of a webserver that does all of these steps. It can be found on Github. I will continue to improve it and it will be features in several future blog posts.

Step 5: Handle the webhook callback

The data send back with the webhook will return the original arguments used to create the hook. This way you can reconstruct the original arguments without needing to maintain a list of outstanding requests. This provides the ability to handle the video in parallel instead of serially.

What else can we do with this?

This could be used to move older videos to cold storage. It could also be used to improve the user experience when a user requests a video. It is possible to use this webhook model to scale up post-processing or video analytics without the need for central coordination.

I hope you found this helpful. If you have any questions please feel free to reach out to us at api_support@een.com