Developer's API Documentation : Connecting & Encoding

Character Set

Toodledo uses UTF-8 for all character encodings. Communication to and from Toodledo should be done with UTF-8.

GET vs POST

Our API will allow any request via either GET or POST. However, you should keep in mind that the maximum length of a GET request is around 2000 characters (depending on the client). For submitting information to Toodledo that could contain more than 2000 characters, you should use POST. Use & to separate parameters in a query string. POSTs should be done with content type " application/x-www-form-urlencoded".

SSL Connections

SSL (https://) connections are required and should be used to protect user's data.

JSON Encoding

Communication to and from the server can be done in JSON or XML.

JSON is a lightweight text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for most scripting languages. --Wikipedia

Toodledo uses normal encoding for JSON objects. This means that the " and \ characters can be escaped with a backslash: \" or \\. They can also be escaped with their Unicode values: \u0022 or \u005C. Other characters can be left unencoded or optionally encoded with their \u#### Unicode escape sequences.

URL Encoding

Any string that you transmit to Toodledo must be encoded such that all non-alphanumeric characters (except -_.~) have been replaced with their %XX equivalent. This is the encoding described in RFC 3986. Spaces may be encoded as either + or %20.

PHP Example

Putting it all together, here is a simple PHP example that demonstrates JSON and URL encoding.

$url = "http://api.toodledo.com/3/tasks/add.php";

$task[0]['title'] = 'task 1 é';
$task[1]['title'] = 'task 2 字';
$task[2]['title'] = 'task 3 "';
	
$json = json_encode($task);
//[{"title":"task 1 \u00e9"},{"title":"task 2 \u5b57"},{"title":"task 3 \""}]

$encoded = urlencode($json);
/*
%5B%7B%22title%22%3A%22task+1+%5Cu00e9%22%7D%2C%7B%22title%22%3A%22task+2+%5Cu5b57
%22%7D%2C%7B%22title%22%3A%22task+3+%5C%22%22%7D%5D
*/

$params = "access_token=".$token."&tasks=".$encoded;
	
$response = curlPOST($url,$params);
/*
[{"id":"123456","title":"task 1 \u00e9","modified":1305646345,"completed":0},
{"id":"123457","title":"task 2 \u5b57","modified":1305646345,"completed":0},
{"id":"123458","title":"task 3 \"","modified":1305646345,"completed":0}]
*/

$added = json_decode($response);