ForumsDevelopersPoor documentation :/
Poor documentation :/
| Author | Message |
|---|---|
|
fahad |
Hi
Take no offense but the online API documentation is very very poor. Many things are completely unclear and many times the wordings are incomplete or misleading. In some areas the older API documentation was better. One good example is that "POST" and "GET" calls. It should be made very clear which methods the new API supports with POST and which are supported only by a GET. In the past I've been able to make "POST" calls for all API 1.0 stuff and it worked. However only 'add' and 'edit' for tasks work with POST now. Another example is that of 'escaping characters'. Toodledo supports its own URL escaping mechanism and in several places it says one thing and then accepts another in reality. Please make it clear with good examples what the server does and does not accept. For example the following string in 'notes' seems to through a 'No Title' error eventhough there's a title but the server apparently was not able to parse it: [{"note"%3A"""%2C"star"%3A"0"%2C"priority"%3A"3"%2C"title"%3A"Adding+a+new+Task%2C+Project+or+C hecklist"%2C"folder"%3A"6355836"%2C"reminder"%3A"0"%2C"tag"%3A""%2C"parent"%3A"196097420"%2C"repeatf rom"%3A"0"%2C"duetime"%3A""%2C"repeat"%3A""%2C"duedate"%3A"0000-00-00"%2C"completed"%3A"0"}] The problem is that with '&qout;'. I dont know what to escape " with. I tried %22, &qout; and " but each of these throw the same error. Many other places the API asks for spaces to be encoded as + but spaces in fact are %20. It seems it supports part one encoding and part another. There's no consistency at all. Please help! |
|
Jake Toodledo Founder |
I am sorry that our documentation isnt clear. I have just gone through the documentation and updated it with some additional information. I also created a new page that explains how to use GET, POST, JSON and URL escaping.
http://api.toodledo.com/2/account/doc_encode.php Also, I modified the API so that all calls can now be done via POST or GET. Toodledo uses standard URL escaping mechanisms. The reason your API call is failing is because the " character needs to be escaped with a backslash as per JSON specifications. Then the entire thing needs to be URL encoded with the % escape sequences per RFC 3986. So " turns into %5C%22. Spaces can be encodes as either + or %20, it doesn't matter. |
|
fahad |
Many thanks for the the writeup! That is most certainly helpful, really.
If at all this is possible: it would be nice to get a more human friendly error back from the server in case it wasn't able to parse parsed JSON/XML/Text etc etc since 'No Title' wasn't very helpful initially. I realize the error 'No Title' was because it wasn't able to parse any text and thus wasn't able to find any 'task' inside passed parameter. If however the server is able to generate a 'invalid encoding found' error of some sort, it would help us debug the problem (it would be even better if it actually told us what characters it wasn't able to parse - much like the ASP/PHP engines that give you precise parsing error messages). But having said that, the additional documentation is much welcomed. Thanks. |
|
fahad |
Oh and thanks for enabling POST on all API calls. This is great because porting from API 1 (which did support both) it was initially confusing why some calls were working and some weren't.
|
|
Jake Toodledo Founder |
We'll see about returning a better error when the JSON is malformed.
|
|
fahad |
Thanks Toodledo - since this warranted a 'new topic' we've posted some more findings of inconsistencies we've found between the APIs here:
http://www.toodledo.com/forums/7/10888/0/improved-examples-in-documentation-please.html |
You cannot reply yet
U Back to topic home
R Post a reply
To participate in these forums, you must be signed in.