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. When using GET, you can use either ; or & to separate parameters. When using POST, you should only use &.

SSL Connections

SSL (https://) connections are always supported and should be used whenever possible 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/2/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 = "key=".$key."&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);