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 have 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 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.