API Documentation

The platform API is a simple restful interface that provides access to and from data and functions based on your application interactions with Overlay.TV. You can get access to this data through XML.

Click here for the related discussion forum.

Article Index

Making Requests
Digest Generation
Authentication
Show User
Create User
Update User
List Users
Show Overlay
Create Overlay
Update Overlay
List Overlay
Destroy Overlay

Making Requests

All requests must be sent as an HTTP POST to api.overlay.tv on port 80. All parameters must be
sent as part of the POST payload, not as part of the URI (query string) with the exception of
_session_id which can be sent via the Cookie header.

Example Request:

POST /api/user/authenticate HTTP/1.1
Host: api.overlay.tv:80
Connection: close
Content-Length: 1234
Content-Type: application/x-www-form-urlencoded
Cookie: _session_id=e266a078fd44397ee13c41298f2cdf19

api_key=22222367b7633fd08687556dce4d187646dfa909&increment=1213386682&v=1.0&digest=aba83aa7811a5f042cde33540cc3556b7cff9bae

There are four parameters that are sent for all API requests; additional parameters are required
for some API methods. Each request must include a digest which is generated from a string of all
parameters. This is generated by the client, and submitted to the server, where a comparison
determines whether the request is valid.

The parameters shown below are used in all requests. The How Used column shows whether the
parameter should be used in the digest and/or the request URL.

Parameter	Type	Description	How Used
api_key	string	The unique public API key provided to a developer by Overlay.TV	digest; request
secret_api_key	string	The unique secret API key provided to a developer by Overlay.TV	digest only
increment	integer	A 32bit integer value that that must increase for each request	digest; request
v	string	The version of the API the application is querying. Currently, only v=1.0 is supported.	digest; request
host_ip	string	The external IP address of the host that is making the request.	digest only
digest	string	See Digest Generation	request only
_session_id	string	The session id must be passed with each call to identify the request to the server. Alternately, this can be submitted in a cookie with the request.	request only

Digest Generation

The digest that is sent with each request allows the server to validate the request is coming from the correct application. It must be generated in the same manner as the server in order for the request to be valid. The following is a step by step guide to the digest generation.

Generate an integer value to be used as the increment.
Create an array of strings containing "parameter=value".
Refer to the table above to see which parameters are required for this step.
Order the array of strings alphabetically.
Join the elements of the array into a string with colons, e.g. key1=value1:key2=value2
Calculate the hexadecimal SHA1 digest of the joined array string.

The examples below demonstrate how to create the digest from the array of parameters required from the digest.

Ruby Digest Sample:

require 'digest/sha1'
def create_digest(opts)
{
   opts_array = []
   #convert the params to a string like 'k1=v1:k2=v2'
   opts.each {|key, value| opts_array << "#{key.to_s}=#{value.to_s}"}
   #sha1 digest the string
   Digest::SHA1.hexdigest(opts_array.sort.join(":"))
}

PHP Digest Sample:

function create_digest($params) {
	// Sort the parameters by key
	ksort($params);
	// Build a new array of "key=value" parameter strings
	foreach($params as $key => $value)
		$param_strings[]="$key=$value";
	// Return the SHA1 digest of the strings joined together by ":"
	return sha1(implode(':',$param_strings));
}

.Net Digest Sample:

using System;
using System.Collections;
using System.Security.Cryptography;
using System.Globalization;

private string createDigest(SortedList url_params)
{
   var digest = "";
   for (int i = 0; i < url_params.Count; i++)
   {
       //convert the key values to a string like 'k1=v1:k2=v2'
       digest = digest + url_params.GetKey(i) + "=" + url_params.GetByIndex(i);
       if (i < url_params.Count - 1)
           digest = digest + ":";
   }

   SHA1 sha = new SHA1Managed();
   
   //sha1 encode the params string (returns a byte array)
   var hash = sha.ComputeHash(Encoding.UTF8.GetBytes(digest));
   var hash_string = "";
   //convert the byte array to a string and then return the digest
   foreach (var hashByte in hash)
       hash_string = hash_string + hashByte.ToString("x2", CultureInfo.InvariantCulture);

   return hash_string;
}

Authentication

URI: /api/user/authenticate

Authenticates an application and provides a session id for future requests.

Response Parameters

Parameter	Type	Description
api_key	string	The unique public API key provided to a developer by Overlay.TV
increment	integer	An integer value that that must increase for each request
v	string	The version of the API the application is querying, only accepts 1.0
digest	string	See Digest Generation
_session_id	string	The session id must be passed with each call to identify the request to the server

Example Request Parameters and XML Response:

POST /api/user/authenticate HTTP/1.1
api_key=22222367b7633fd08687556dce4d187646dfa909&increment=1213386682&v=1.0&digest=aba83aa7811a5f042cde33540cc3556b7cff9bae&_session_id=e266a078fd44397ee13c41298f2cdf19

<session>
  <key type="string">185c9977dc892dd11d88bb6466a58e5c</key>

  <user>
    <id type="integer">1</id>
    <username type="string">jreynolds</username>
  </user>
</session>

Show User

URI: /api/user/show

Returns the details of a specific user.

Request Parameters

Parameter	Type	Description
user_id	integer	The user id the application is requesting details for

Example Request Parameters and XML Response:

POST /api/user/show HTTP/1.1
user_id=260&api_key=22222367b7633fd08687556dce4d187646dfa909&increment=1213387859&v=1.0&digest=b7ed48026ab14ac69c2a056a0cf93ffe77d6ea82&_session_id=e266a078fd44397ee13c41298f2cdf19

<user>
  <created_at type="datetime">2008-06-13T20:10:59Z</created_at>
  <email>jreynolds@overlay.tv</email>

  <id type="integer>260</id>
  <login>jreynolds</login>
  <updated_at type="datetime">2008-06-13T20:10:59Z</updated_at>
</user>

Create User

URI: /api/user/create

Creates a user.

Request Parameters

Parameter	Type	Description
login	string	The unique login for the user
email	string	The unique email of the user
password	string	The password the user can use to login
birthday	string	Example: January 1, 1963
gender	string	Values: m/f/x (x meaning not disclosed, always lower case)
newsletter	boolean	Determines if the user will receive email notifications from Overlay.TV

Example Request Parameters and XML Response:

POST /api/user/create HTTP/1.1
login=jreynolds&email=jreynolds@overlay.tv&password=jreynolds&api_key=22222367b7633fd08687556dce4d187646dfa909&increment=1213389466&v=1.0&digest=df301936fff0ecd562a65d6f4d23071dc32fe663&_session_id=e266a078fd44397ee13c41298f2cdf19


<user>
  <created_at type="datetime">2008-06-13T20:37:46Z</created_at>
  <email>jreynolds@overlay.tv</email>
  <id type="integer">263</id>

  <login>jreynolds</login>
  <updated_at type="datetime">2008-06-13T20:37:46Z</updated_at>
</user>

Update User

URI: /api/user/update

Updates a user.

Request Parameters

Parameter	Type	Description
email	string	The unique email of the user
password	string	The password the user can use to login

Example Request Parameters and XML Response:

POST /api/user/update HTTP/1.1
email=changed@overlay.tv&id=269&api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213390145&v=1.0&digest=e2d3baee928c51d5c8b24fc1e58a3c8c3abb9c53&_session_id=e266a078fd44397ee13c41298f2cdf19

<user>
  <created_at type="datetime">2008-06-13T20:49:04Z</created_at>
  <email>different@overlay.tv</email>
  <id type="integer">269</id>

  <login>jreynolds</login>
  <updated_at type="datetime">2008-06-13T20:49:05Z</updated_at>
</user>

List Users

URI: /api/user/list

Lists all users created by the application.

Request Parameters

Parameter	Type	Description
page optional	integer	The page of users to request (default: 1)

Example Request Parameters and XML Response:

POST /api/user/list HTTP/1.1
api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213390235&v=1.0&digest=ad41219f142db5763626dabcb54e4007b5db9e4f&_session_id=e266a078fd44397ee13c41298f2cdf19

<page>
	<paging>
	  <current>1</current>

	  <pages>1</pages>
	  <size>2</size>
	</paging>
	<users>
	  <user>

	    <created_at type="datetime">2008-06-13T20:50:34Z</created_at>
	    <email>jreynolds@overlay.tv</email>
	    <id type="integer">270</id>
	    <login>jreynolds</login>

	    <updated_at type="datetime">2008-06-13T20:50:34Z</updated_at>
	  </user>
	  <user>
	    <created_at type="datetime">2008-06-13T20:50:34Z</created_at>
	    <email>jduff@overlay.tv</email>

	    <id type="integer">271</id>
	    <login>jduff</login>
	    <updated_at type="datetime">2008-06-13T20:50:34Z</updated_at>
	  </user>

	</users>
</page>

Show Overlay

URI: /api/overlay/show

Shows details of an Overlay.

Request Parameters

Parameter	Type	Description
user_id	integer	The id of the user the Overlay is owned by
id	integer	The id of the Overlay to show the details for

Example Request Parameters and XML Response:

POST /api/overlay/show HTTP/1.1
id=4015&user_id=16&api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213638874&v=1.0&digest=23ff998409cc6f7e8deba48ccc5f99081c340019&_session_id=e266a078fd44397ee13c41298f2cdf19

<overlay>
  <created_at type="datetime">2008-06-16T17:54:31Z</created_at>

  <creator_id type="integer">20</creator_id>
  <description></description>
  <id type="integer">4015</id>
  <thumbnail>/images/overlays/324986a01dfb012b016c001b63983c79_sthumb.png</thumbnail>

  <title>Introduction to the iGoogle Sandbox</title>
  <updated_at type="datetime">2008-06-16T17:54:34Z</updated_at>
  <media_asset>
    <created_at type="datetime">2008-06-16T17:54:31Z</created_at>

    <creator_id type="integer">20</creator_id>
    <description></description>
    <id type="integer">507</id>
    <original_url>http://www.youtube.com/watch?v=H6KVwATfCdM</original_url>

    <title>Introduction to the iGoogle Sandbox</title>
    <updated_at type="datetime">2008-06-16T17:54:31Z</updated_at>
    <url>http://www.example.com/video/youtube?url=http://www.youtube.com/watch?v=H6KVwATfCdM</url>
    <media_provider>

      <id type="integer">320</id>
      <url>http://www.youtube.com</url>
    </media_provider>
  </media_asset>
</overlay>

Create Overlay

URI: /api/overlay/create

Creates an Overlay.

Request Parameters

Parameter	Type	Description
overlay_url	string	The URL to the video asset to create an Overlay for
user_id	integer	The id of the user the Overlay will be created for. If not supplied the Overlay will be created for the owner of the developer key

Example Request Parameters and XML Response:

POST /api/overlay/create HTTP/1.1
overlay_url=http://www.youtube.com/watch?v=H6KVwATfCdM&user_id=16&api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213630113&v=1.0&digest=b24e462bcca3a2b6d615ded744026c571196fbb9&_session_id=e266a078fd44397ee13c41298f2cdf19

<overlay>
  <created_at type="datetime">2008-06-16T15:28:34Z</created_at>
  <creator_id type="integer">16</creator_id>

  <description></description>
  <id type="integer">4010</id>
  <thumbnail>/images/overlays/ce938a801de6012b0168001b63983c79_sthumb.png</thumbnail>
  <title>Introduction to the iGoogle Sandbox</title>

  <updated_at type="datetime">2008-06-16T15:28:34Z</updated_at>
  <media_asset>
    <created_at type="datetime">2008-06-16T15:28:34Z</created_at>
    <creator_id type="integer">16</creator_id>

    <description></description>
    <id type="integer">502</id>
    <original_url>http://www.youtube.com/watch?v=H6KVwATfCdM</original_url>
    <title>Introduction to the iGoogle Sandbox</title>

    <updated_at type="datetime">2008-06-16T15:28:34Z</updated_at>
    <url>http://www.example.com/video/youtube?url=http://www.youtube.com/watch?v=H6KVwATfCdM</url>
    <media_provider>
      <id type="integer">320</id>

      <url>http://www.youtube.com</url>
    </media_provider>
  </media_asset>
</overlay>

Update Overlay

URI: /api/overlay/update

Updates an Overlay.

Request Parameters

Parameter	Type	Description
id	integer	The id of the Overlay to be updated
user_id	integer	The id of the user the Overlay is owned by
title optional	string	The title of the Overlay
description optional	string	The description of the Overlay

Example Request Parameters and XML Response:

POST /api/overlay/update HTTP/1.1
title=Updated+Overlay+Title&id=4011&user_id=17&api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213630547&v=1.0&digest=1a11ceb97efd9a0ad36859d3e5a03aef382aac5b&_session_id=e266a078fd44397ee13c41298f2cdf19

<overlay>
  <created_at type="datetime">2008-06-16T15:35:44Z</created_at>
  <creator_id type="integer">17</creator_id>
  <description></description>
  <id type="integer">4011</id>

  <thumbnail>/images/overlays/cef8b1a01de7012b0169001b63983c79_sthumb.png</thumbnail>
  <title>Updated Title</title>
  <updated_at type="datetime">2008-06-16T15:35:48Z</updated_at>
  <media_asset>

    <created_at type="datetime">2008-06-16T15:35:44Z</created_at>
    <creator_id type="integer">17</creator_id>
    <description></description>
    <id type="integer">503</id>

    <original_url>http://www.youtube.com/watch?v=H6KVwATfCdM</original_url>
    <title>Introduction to the iGoogle Sandbox</title>
    <updated_at type="datetime">2008-06-16T15:35:44Z</updated_at>
    <url>http://www.example.com/video/youtube?url=http://www.youtube.com/watch?v=H6KVwATfCdM</url>

    <media_provider>
      <id type="integer">320</id>
      <url>http://www.youtube.com</url>
    </media_provider>
  </media_asset>

</overlay>

List Overlays

URI: /api/overlay/list

List Overlays created for a user, product, or developer key. Requesting with no parameters will return a list of overlays created for a the authenticated developer key.

Request Parameters

Parameter	Type	Description
user_id optional	integer	The user id to list Overlays for
product_url optional	string	The product URL
page	integer	The page of overlays to request (default: 1)

Example Request Parameters and XML Response:

POST /api/overlay/list HTTP/1.1
user_id=18&api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213638399&v=1.0&digest=670cb6c68e085828f6b87f46d10e7bb569a2f02b&_session_id=e266a078fd44397ee13c41298f2cdf19

<page>
	<paging>
	  <current>1</current>
	  <pages>1</pages>
	  <size>2</size>

	</paging>
	<overlays>
	  <overlay>
	    <id type="integer">4012</id>
	    <thumbnail>/images/overlays/13ed6a001dfa012b016a001b63983c79_sthumb.png</thumbnail>

	    <title>Introduction to the iGoogle Sandbox</title>
	  </overlay>
	  <overlay>
	    <id type="integer">4013</id>
	    <thumbnail>/images/overlays/1814ac501dfa012b016a001b63983c79_sthumb.png</thumbnail>

	    <title>Vitalic: &quot;U and I&quot;</title>
	  </overlay>
	</overlays>
</page>

Destroy Overlay

URI: /api/overlay/destroy

Deletes an Overlay.

Request Parameters

Parameter	Type	Description
user_id	integer	The user id that owns the Overlay
id	integer	The Overlay id to destroy

Example Request Parameters and XML Response:

POST /api/overlay/destroy HTTP/1.1
id=4016&user_id=21&api_key=2ac12367b7633fd08687556dce4d187646dfa909&increment=1213639210&v=1.0&digest=5b067c59cff2235ab0da1025ef446d74d015e0ac&_session_id=e266a078fd44397ee13c41298f2cdf19

<overlay>
  <id type="integer">4016</id>
</overlay>

Overlay.TV Labs

Navigation

Docs & Files

New forum topics

Search

User login

Article Index

Making Requests

Digest Generation

Authentication

Show User

Create User

Update User

List Users

Show Overlay

Create Overlay

Update Overlay

List Overlays

Destroy Overlay