Building Robust Applications in a Shared Environment

The Video Cloud Media APIs provide powerful access to your Video Cloud media library. You can extract information about videos and playlists and even modify your videos and playlists from any number of programming languages that support HTTP-based REST APIs.

Because our customers depend on the Video Cloud platform to reliably power their web sites and applications, we must ensure that all access points are protected in such a way as to prevent abuse and monopolization. Unfettered access would allow this shared environment to be consumed by a subset of users, causing all users to experience a material degradation in the quality and performance of various interactions.

With this in mind, it is important to understand how to develop applications that can interact with the Video Cloud service in a reliable fashion. In order to assist your development using the Video Cloud Media APIs, this document outlines the mechanisms we’ve put in place to safeguard the system so it is as robust as possible, as well as the steps you can take to make sure your applications are safe and reliable so your end users receive the quality of service you expect.

Serial Processing

In order to build an integration that is as robust as possible you should develop your applications in a serial fashion. This means queuing up multiple requests in your application and then executing those functions against the Video Cloud Media APIs one after another until the queue is completed. Developing in this fashion has several advantages, especially for heavy requests such as the create_video method that requires transferring a file over the internet.

Similar to how uploads are handled by the Video Cloud Studio Media module, uploading files one at a time enables each individual file to transfer using the entire available bandwidth. This will significantly minimize network interruptions during the transfer, and if there are any interruptions, the effect is limited to a single file as opposed to several.

Error Handling

You should also make sure your applications know how to prevent and recover from issues once the request has been received by the Video Cloud system. In order to provide your applications reliable feedback, we’ve built a thorough set of error codes that can be used to properly react when actions do not complete as expect while using the Media Write APIs.

One of the most important error codes to handle is the 213 - ConcurrentWritesExceededError. This error will be returned to any Media Write API request that can not be handled by the Video Cloud system due to other Media Write API requests you are executing at the same time. Applications that do not utilize a queuing system to execute requests using the Media APIs are likely to encounter this error. If your applications are used by multiple users, this error is even more likely to occur when different users perform tasks at the same time.

As described above, building your application in a serial fashion should prevent your application from generating this error. However, you may still receive this error if other applications at your organization are running simultaneously. Due to possible conflicts, it is important to be able to recover from this error. Even if you know your application is the only one integrating with the Video Cloud service, in order to ensure future functionality, include retry logic into your applications.

Retry Logic

Building your applications so they are capable of recovering from error conditions is crucial. Implementing retry logic will allow your applications to re-attempt any requests that generated an error which might succeed without manual intervention. In most situations, retry logic can be as simple as inspecting the response received from the Video Cloud service. If the response was an error such as the 213 error, re-attempting the same call again may allow the request to be accepted. When developing retry logic, you should limit the number of attempts and consider adding delays between tries to improve the chances of success.

Many error messages should not trigger a retry attempt. Some error messages are reported when an API is misused and will always return the same error despite retry attempts. Instead of retrying these requests, your application should be updated to prevent them in the future. An example of this type of error is the 210 – InvalidTokenError. An error like this requires manual intervention, so performing a retry is of no value.

Another recommendation is to add delays in between retry attempts. In some situations, adding a short delay between retry attempts will significantly improve the chances that the second attempt will succeed. The actual time to delay between retry attempts should only be a few seconds at most, but you should consider the type of request being made and determine an appropriate time for your application.

For a code example that shows how to build this type of retry logic, see Media Write API: PHP Example – Upload Video.