Overview
The SecureVideo.com API is a RESTful API which enables software-to-software use of the SecureVideo system.
- All server-to-server requests must be made via SSL
- Every request must be authenticated using Basic Authentication over SSL
- The base URI is https://api.securevideo.com/
- All content is passed as JSON
- HTTP Methods used are GET, PUT, POST, and DELETE; POST creates a new record, and PUT updates an existing record
- HTTP Response Status Codes are used extensively to provide results
- Response data is simple to work with, as no envelopes are used--if a Success status code (200s) is returned, the returned data is the JSON object representing the requested resource; if there was a problem with the request (400s) or an internal error (500s), the returned data will be a JSON error message
Our API allows you to quickly integrate a videoconferencing platform with excellent video quality. To use our API, you must first contact our Sales team to get a custom quote, which will depend on your anticipated use cases, request volumes, and engineering support needs. Once you have signed an API Licensing Agreement, our Support team will provide you with the keys you need in order to use our API.
Authentication
Once you are set up as an API customer, you will have access to two keys which are to be used with the API.
- API Identifier: a public key uniquely identifying the SecureVideo.com customer
- API Secret Key: a private key to be used only in server-to-server API calls
Every server-to-server API request must be made over HTTPS using Basic Authentication. You should construct your HTTP Authorization Header as follows:
- Combine your API Identifier and API Secret Key into a single string separated by a colon, for example: "8ded5a89051a9a01a389bcdf1e174:99176b1d244c484ed65dd792abc1"
- Encode the resulting string using the RFC2045-MIME variant of Base64 (You can use a site like base64encode.org)
- Set the Authorization header to “Basic”, then a space, then the Base 64 encoded string
Here's how you could code it in C#:
// Set uri
string uri = "https://api.securevideo.com/session/2942";
// Create SecureVideo API authorization token
// Concatenate API Identifier and Secret Key with a colon separator
string colonSeparatedToken = customer.ApiIdentifier + ":" + customer.ApiSecretKey;
// Convert the colon separated token to byte array using ASCII encoding
byte[] authorizationHeaderBytes = Encoding.ASCII.GetBytes(colonSeparatedToken);
// Convert the byte array into a Base 64 string
string base64AuthorizationHeader = Convert.ToBase64String(authorizationHeaderBytes);
string webResponseJson;
using (WebClient webClient = new WebClient())
{
webClient.Proxy = null; // In .NET WebClient, specify Proxy for performance
webClient.Headers[HttpRequestHeader.ContentType] = "application/json; charset=utf-8";
webClient.Headers[HttpRequestHeader.Authorization] = "Basic " + base64AuthorizationHeader;
// The .DownloadString() does an HTTP GET. To do a POST, you would use webClient.UploadString(uri, "POST", requestData)
webResponseJson = webClient.DownloadString(uri);
}
// Handle errors and webResponseJson in your own way here...
Here is an example Authorization Header: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Every client-side (browser) call made to an API server must contain your API key in the query string, and must not contain your secret key. You must keep the secret key a secret! It must never be placed in any code which appears in a browser, and it must only ever be transmitted from your server to our server. Any other use or dissemination of the secret key is a violation of the API terms of service.
You never need to pass SecureVideo.com user e-mail or passwords to the API, unless you are creating a user or specifically updating those fields in the Set User API call. You will always just pass your secret key and API key, and then the user ID (from your system) of the user on whose behalf you wish to perform the action.
Format
The SecureVideo.com API is a JSON-only API. You must set the Content-Type HTTP Header in all requests to application/json. All content returned will also be in JSON.
HTTP Methods
As with many RESTful APIs, the SecureVideo API takes advantage of the HTTP method used in order to determine which operation to perform. In general, the following HTTP methods are used in the API:
- GET - retrieves an existing object or list of existing objects (users, sessions, etc.)
- POST - creates one new object
- PUT - updates one existing object
- DELETE - deletes one existing object
HTTP Status Response Codes
Every server API call will return an appropriate HTTP status code, and may contain data or a problem message in JSON. As you develop your solution, you will find it convenient to be able to view these status codes (as well as HTTP headers) using Fiddler, curl, or a similar tool.
- 200s = Success
- 200 = OK – the request was successful
- 201 = Created – the request was successful, and a new record was created. This is returned by all successful HTTP POST methods.
- 204 = No Content – the request was successful, but no content is returned. This is returned by all successful HTTP DELETE methods.
- 400s = Bad Request (something you need to fix)
- 400 = Bad Request – this generally occurs when the JSON content is malformed, and cannot be understood by the API server
- 401 = Unauthorized – this occurs when your API Identifier and API Secret Key are either incorrect, were not Base64 encoded correctly, or the HTTP Authorization header was not set correctly
- 403 = Forbidden – this occurs when you have identified a resource to act upon, but you do not have permission to perform the action upon the resource, for example you request GET /User/2112, the user exists, but is not one of your company’s users; or, you attempt to delete a user who is an Administrator
- 404 = Not Found – this occurs when the resource you specified does not exist, for example you request GET /User/2112, and this user ID does not exist
- 405 = Method Not Allowed – this occurs when the method (GET, POST, PUT, or DELETE) is not permitted upon the resource you specified, for example you attempt to DELETE /Usage
- 412 = Request Must Be From a Whitelisted IP Address – you can specify one or more IP addresses that are authorized to access our API. This can only be set by contacting our support team. If a server attempts to access our API which is not at a whitelisted address, the 412 error is returned. By default, we will leave the IP Address on your My Account > API tab to "0.0.0.0", which will allow any address to access the API.
- 429 = Too many requests – this occurs when you have exceeded the maximum hourly quota for transactions, which is set by us according to our API Service Agreement, and is viewable by you on your My Account > API tab. There is also a system maximum of 100,000 requests per hour for any one customer, which can only be increased by our adding API processing resources. Any value set in the My Account > API tab that is greater than the system maximum will be reduced to equal the system maximum until more processing resources can be added.
- 500s = Error (something we need to fix) - because 500 errors are something we need to fix, for security reasons we return a fairly generic error message, and then will determine the exact cause of the error by examining our logs
- 501 = Not Implemented Yet – this occurs if we plan to implement a method but have not yet done so.
Almost always, 400 and 500 errors will return a JSON object with a single "Message" property which summarizes the error, either specifically (400 errors) or generically (500 errors). In some cases where the API has never been properly invoked (e.g., your network is down, or you try to access the web server root via "GET https://api.securevideo.com/", or the web server had some internal error where it could not properly initialize the API site), it is possible that you could receive an HTML body instead of a JSON body.
This article was last reviewed by our Support team on March 28, 2018.
