API

Introduction

ToWatchList uses a basic REST API to allow for both sending and retrieving data from the server. HTTPS is recommended for all API queries for user security. The content type of all responses is 'application/json' and the data is formatted as JSON array of key/value pairs.

Getting a User's API Key

To use the public ToWatchList API, an application should convert the user's login email and password to an API key:

curl -u 'user@host.com:password' 'https://towatchlist.com/api/v1/getkey'

A matching username & password will return status code 200 with the hashed key within a JSON object like this:

{"result":"1","key":"123abc123abc123abc123abc123abc123abc123a"}

Incorrect username & password combinations return status code 401 and:

{"result":"2","info":"incorrect username or password"}

Once the API key is obtained, it is suggested that the username and password be purged for enhanced user security. Users can reset their API key from the tools page at any time if it is leaked or abused.

Scanning URLs for Videos

To tell ToWatchList to scan a page for embedded videos, an application or script can submit a GET request to the URL scanner with this syntax:

curl 'https://towatchlist.com/api/v1/scanurl?l=[URL]&uid=[API Key]'

Where the [URL] must be encoded with the JavaScript encodeURIComponent() function, and the [API Key] is the value returned from the function above. For example, if an app wanted to tell ToWatchList to scan http://thesite.com/page.php the query would look like this:

curl 'https://towatchlist.com/api/v1/scanurl?l=http%3A%2F%2Fthesite.com%2Fpage.php&uid=123abc123abc123abc'

The response will have status code 200 and be a JSON encoded array of keys and values like these examples:

{"result":"1","info":"Found 2 new marks. Found 1 existing mark."}
{"result":"1","info":"Found 1 new marks"}
{"result":"1","info":"Found 2 existing marks."}

The result value indicates how the request was processed and the info key gives a short, human-readable statement about the result. Above, the result value of 1 is considered a successful scan. However, if things worked successfully but no videos were found, the API returns HTTP status code 200 and result code 2:

{"result":"2","info":"No videos found."}

If an invalid API key is passed (perhaps because it was reset), the result code will be 3 with status code 401:

{"result":"3","info":"Bad API Key."}

Finally, other errors, such as if the passed URL does not resolve, will generate a result code of 4 with status code 400:

{"result":"4","info":"Unknown Error."}

Questions

Did you find this useful? Do you have questions, concerns, or suggestions about the API? Please don't hesitate to contact me.