ForumsDevelopersPoor documentation :/


Poor documentation :/
Author Message
fahad

Posted: May 16, 2011
Score: 0 Reference
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
Posted: May 17, 2011
Score: 0 Reference
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

Posted: May 17, 2011
Score: 0 Reference
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

Posted: May 17, 2011
Score: 1 Reference
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
Posted: May 17, 2011
Score: 0 Reference
We'll see about returning a better error when the JSON is malformed.
fahad

Posted: May 18, 2011
Score: 0 Reference
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.