Introduction | WS.WebTV API Reference | WebTV Solutions

Print

The WS.WebTV API has been designed to allow the integration/interaction between other applications and the WebTV. It was launched with WS.WebTV version 1.8 and with each new version we have added new functions. Our intention is to continue adding more functions, over time.

Managing API Credentials

Before using the API the first thing you need to do is to create a Credential in the WebTV. Please note that you can create any number of Credentials.

In order to create/edit an API Credential:

1. Goto to API...

2. Once on the Credential list...
(A) To create an API Credential click on "New Credential" button.
(B) To edit an existing API Credential click the corresponding "pencil" icon.


The creation and edition interfaces are very similar, however, when you are editing a Credential you will see additional information.

3. Properties...
• Title: Enter a descriptive title for your own reference.
• Requests expiration time: This is the maximum time (in seconds), elapsed from the request generation date, that a request will be accepted by the system.
• Allowed Referers: (Optional) If the Credential is being generated in order to use it on a Web page (Javascript, for example), then you can specify the allowed referer domains (separated by comma). Please note that if the Credential is configured to restrict by referers but no referer info is provided by the origin server the request will be discarded unless you also add the "blank" referer to the list.
Example: To allow request from "mydomain.com" and "blank" you should enter: mydomain.com, www.mydomain.com, blank
• Enable Statistics: When enabled the system will register statistics for the Credential.
4. Permissions... Select the permissions (general and specific) you want to grant to the Credential.
Specific permissions allows some sections of the API to have different permissions than the general ones.


After saving (creating) the Credential, the system will generate a "Key ID" and "Key (Shared) Secret":
• Key ID: This ID must be used publicly to identify the requests by this Credential.
• Key (Shared) Secret: Be careful with this Key as it will be used to generate the validation signatures; therefore, you should never expose it publicly. This Key must only be "known" by the WebTV and your application.
NOTE: The aforementioned Keys will only be generated once (at the Credencial creation).

API Base URL

The API URL is the Base URL of your WebTV followed by "/api.php".
Example:
If your WebTV URL is http://www.mywebtvdomain.tv
...then all API requests must be sent to http://www.mywebtvdomain.tv/api.php (https is strongly recommended!)

NOTE: All request are performed using GET and POST.

Security

Required info

Every request you send to the API must have the following GET vars in the request URL:

Example:
https://....../api.php?go=clips&do=get&iq=5&timestamp=1427282901&salt=1e05489590729c06363f6ddfff5c99ff&key=57a3f24f8abd71cdde44c3e3fb675bc7&signature=Y98d2tB3oMPKwIJ8PJEZXG72Nd1zqn27yUCUsP8phHs%3D

Authentication: Verification Signature

Except for those cases when you have allowed unsigned requests, all the API requests require a verification signature. The signature (hash) is generated from the concatenation of the salt and timestamp, using base64 + HMAC SHA256 with the "Key (Shared) Secret".

Pseudocode example:

signature = URL ENCODE ( base64 ( HMAC SHA256 ( ( "salt" + "timestamp" ) , KEY SECRET ) ) )

PHP example:

$API_KEY_SECRET = "credential key secret";
$salt = md5(mt_rand());
$timestamp = time();
$signature = urlencode(base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_KEY_SECRET, true)));

If you are working with other languages you may want to take a look at the following document:
Examples of creating base64 hashes using HMAC SHA256 in different languages

Important Recommendations

1. Secure your requests by using HTTPS in your API request URLs. This requires having a valid SSL certificate in your WebTV's server. This is specially important when dealing with User-related requests.

2. On the Web, always try to avoid sending requests to the API using a Front-End application.
Example: If you need to use Javascript in order to fetch information then avoid doing the requests directly from Javascript. Instead, you can use a Back-End (server-side) application to do the requests to the API and then send (only) the appropriate result to Javascript. Additionally, never include the API Key (Shared) Secret into a Javascript because it would be publicly accessible (!).

3. Never expose the API Key (Shared) Secret and do your best to protect it. If you are using a Front-End application to send requests to the API (for example, a mobile App), then make sure the Secret Key is really secured or use a Back-End application to send the requests to the API and the result to the App. Also, always use HTTPS and avoid managing sensitive information from the App.

Return Format

By default, the API will return the result in JSON format; however, you can ask the return in JSONP format (with callback), by adding the GET vars "format" and "callback" to the request URL.
Example:
https://....../api.php?go=clips&do=get&iq=5&key=57a3f....&format=jsonp&callback=myfunction

Cache

The system caches "GET" requests for better performance. In case you (really) need an uncached result then you can ask it by adding the GET var "cache" to the request URL.
NOTE: In order to adjust the cache "life" time, do so from Configuration > Settings > Cache and change the "API Cache Life" setting.
Example:
https://....../api.php?go=clips&do=get&iq=5&key=57a3f....&cache=0

IMPORTANT: Make sure the folder api/temp/cache has write permissions. You can verify this with the WebTV Diagnostics tool.

General Error Messages

The following are errors which can be returned by any request:

• REQUEST_ERROR | Missing signature:
The Credencial permissions only allow signed requests and no signature was provided.

• REQUEST_ERROR | Invalid request (missing required info):
All, or part, of the required info (GET vars) is missing on the request URL.

• REQUEST_ERROR | Invalid API Key ID:
The supplied API Key ID was not found in the system.

• REQUEST_ERROR | Invalid request (time out):
The request is older than the "Requests expiration time" specified in the Credential.

• REQUEST_ERROR | Permission error (GET, MODIFY, CREATE, DELETE):
The Credential does not have the permission required to perform the request.

• REQUEST_ERROR | Wrong signature:
The provided signature does not match the expected signature.

• REQUEST_ERROR | Not allowed:
The Credential does not allow request sent from the referer.