Complete documentation
30 views
Skip to first unread message
Michael Xavier
Oct 23, 2011, 10:09:30 PM10/23/11
to Remember The Milk API
I'm working on language bindings for the RTM API and I'm having a very
hard time working with the JSON response API. I wanted to know if RTM
has anyone working on improved documentation. Providing a simple XML
"example" response is not good enough for a few reasons:
1) Most of the XML examples omit fields or make list elements blank,
which offers no insight into what the contents would be.
2) There's no XSDs for anyone to integrate against so they presumably
have to fiddle around with the data in their own RTM account to
explore the possible values for things.
3) There's 0 documentation of what the JSON response looks like for
any of the methods other than in the general JSON response overview.
4) The JSON schema itself is consistent but consistently antipattern.
If tasks are nested within an object's response, and there is only one
of them, it can be found in {tasks: {task: {....}}, but if there are
more than one, then {tasks: {task: [{...}, {...}]}}. The datatype
changes for absolutely no reason depending on how many tasks there are
(1 vs many).
So is anyone working on the response documentation? Such incomplete
documentation makes the process of coding against the API *far* more
difficult than it has to be. Secondly, is there any plan to clean up
some of these more pathological design decisions? I don't mean to
sound harsh but participation is a lot easier when you put a little
more care into the API docs.
hard time working with the JSON response API. I wanted to know if RTM
has anyone working on improved documentation. Providing a simple XML
"example" response is not good enough for a few reasons:
1) Most of the XML examples omit fields or make list elements blank,
which offers no insight into what the contents would be.
2) There's no XSDs for anyone to integrate against so they presumably
have to fiddle around with the data in their own RTM account to
explore the possible values for things.
3) There's 0 documentation of what the JSON response looks like for
any of the methods other than in the general JSON response overview.
4) The JSON schema itself is consistent but consistently antipattern.
If tasks are nested within an object's response, and there is only one
of them, it can be found in {tasks: {task: {....}}, but if there are
more than one, then {tasks: {task: [{...}, {...}]}}. The datatype
changes for absolutely no reason depending on how many tasks there are
(1 vs many).
So is anyone working on the response documentation? Such incomplete
documentation makes the process of coding against the API *far* more
difficult than it has to be. Secondly, is there any plan to clean up
some of these more pathological design decisions? I don't mean to
sound harsh but participation is a lot easier when you put a little
more care into the API docs.
Jason Emerick
Oct 23, 2011, 11:53:42 PM10/23/11
to remembert...@googlegroups.com
This is one of the reasons I wrote milkapi.com so that I could easily get the responses from the API to use while developing scripts or apps.
Hopefully it can help you.
Thanks,
Jason
Sent from my iPad
Michael Xavier
Oct 24, 2011, 4:18:53 PM10/24/11
to Remember The Milk API
That's pretty handy. It doesn't do much in the way of explaining
possible values for the fields and such but I can see using it as a
handy development tool. It is no substitution for proper docs but I
really appreciate your efforts to make integration with RTM easier.
On Oct 23, 8:53 pm, Jason Emerick <jemer...@gmail.com> wrote:
> This is one of the reasons I wrote milkapi.com so that I could easily get the responses from the API to use while developing scripts or apps.
>
> Hopefully it can help you.
>
> Thanks,
> Jason
>
> Sent from my iPad
>
possible values for the fields and such but I can see using it as a
handy development tool. It is no substitution for proper docs but I
really appreciate your efforts to make integration with RTM easier.
On Oct 23, 8:53 pm, Jason Emerick <jemer...@gmail.com> wrote:
> This is one of the reasons I wrote milkapi.com so that I could easily get the responses from the API to use while developing scripts or apps.
>
> Hopefully it can help you.
>
> Thanks,
> Jason
>
> Sent from my iPad
>
Reply all
Reply to author
Forward
0 new messages