Improve kobotoolbox adaptor: functions, documentation and examples

[aleksa-krolls]

The first part of this issue is to review & audit the existing docs for the Kobo adaptor to determine what the "best-class" version of the documentation on the adaptor functions and examples could look like.

To check:

• does an example exist for each function?
• are options documented? (And how do we do this?)
• are API limits documented? (And how do we do this?)
• is the configuration schema (and optional parameters) clearly documented?

The notes from the review have been noted to inform improvements in this comment. The objective is to clean up API Signatures for Kobotoolbox adaptor using CommCare and HTTP as references.

[josephjclark]

Here is my feedback for the API reference.

I am going to make a few comments on the API itself while I'm here, although that's technically not part of this work

tl;dr

• need typedefs for params
• Would benefit from a few more examples
• No docs at all on state transformation

General

• There is no mention of API limits and/or paging. I don't know if either are relevant
• In this API, the params object feels more like options, and I would be in favour of changing the APIs to be a bit cleaner
• The docs are very brief and the semantics of it are generally very loose, making a small and simple API hard to understand and work with
• At least the signatures are nice and consistent with a (params, callback) structure

getDeploymentInfo

• params are not documented in detail (needs a typedef)
• params language is vague - it talks about a fetch or filter but neither thing is explained
• Also it says "a specific form" but if I don't pass a form id or filter, will it return all forms?
• callback function is not well described (to be fair, it never is). It's actually an operation signature.
• No documentation on the returned/transformed state
• There is one decent example, although I'm not a great fan of using the callback to log
• I'd like to see three examples: get info for a form, get with filter, and get with callback.
• There is no direct mapping to the kobotoolbox API or docs (again, this is a general problem across our docs)
• API note: I think the signature should be getDeploymentInfo(formId, options, callback)

getForms

• Is this a HTTP function or a high level helper? It mixes metaphors. It talks about making a request an says you can attach headers etc. But as it's called getForms it should really be abstracting out the HTTP API.
• params is not documented
• Make a request to get the list of forms - what forms? All forms? Can I filter?
• API note: is this any different from getDeploymentInfo?
• No docs on state transformation - what does my returned state.data look like? What does this actually get?
• There's one example which uses an empty object for params (not nice), and has a console.log callback (not a fan). I prefer to see get all forms as one example, and maybe get with callback as another. If those params are actually important (and I doubt it) we should add an example for them too

getSummissions

• Same feedback as getDeployment info really
• Get submissions for a specific form but params says it allows a filter? So is it for one form or can I get all submissions and filter?

[josephjclark]

There is clear documentation on the configuration. Like every other adaptor I don't think its well presented, but that's a wider problem

[josephjclark]

There is one example, with a score of 0, with no code. So that needs sorting out.

Also the readme has quite a nice example of filtering on submissions

[josephjclark]

I'm just looking at doing a sweep of docs here to make this our gold standard for documentation.

My problem is: the API really isn't very clean, and it's hard to provide clean documentation for an unclean API!

For example: getForms mixes http concepts and kobo concepts. I don't think a getForms function should expose HTTP headers directly - just give me the forms and expose filter/query options.

Another problem with the actual API of getForms is that it actually just gets /assets, and according to kobo docs that returns list of all assets, including forms/projects, questions, blocks, templates, collections. And there's no filter that I can see.

Another big problem with kobotoolbox is that kobo themselves don't really document their own APIs. We have a real opportunity to provide a nice clean interface to kobo.... but only if we can work out what that API is. Maybe we can reverse engineer it from the source, or just guess a bit and work it out.

Furthermore, I can't write good examples if I don't know how the adaptor or API works.

So, I'm a bit stuck here.

[martalovescoffee]

Please check in with @josephjclark if you need to and update the estimate @hunterachieng accordingly.

[aleksa-krolls]

@hunterachieng given the chat with joe about some design questions he wants to revisit, you do not need to worry about this issue for this next sprint. Instead we'll focus on #934, so fyi I've put this new issue in sprint backlog (and this one Joe will revisit the spec for a future sprint)