ICEES API documentation - user requests

[karafecho]

This issue is to suggest that we expose documentation on cohort descriptions, clinical feature variables, environmental exposures feature variables, and binning strategies via the API. At one point, we had documentation linked out from the top left corner of the Swagger UI (see screenshot below), but this was deemed inappropriate, and so, the documentation was removed.

I've received requests from potential users (Alex's DSiP students) to expose the following in a human-readable format:

1. Expose cohort descriptions via ICEES+ Swagger UI
2. Stand-up a video tutorial of how to ask ICEES+ a query

In response, I've updated or created new documentation, which I added to this G-folder. I also reviewed the ICEES Overview page, which is linked out from the Swagger UI. While the overview points to a very outdated website, the tutorial is pretty nice (if I do say so myself!), albeit a bit outdated.

Here are my thoughts:

1. We should maintain the documentation within the G-folder as "living docs", so that we can more readily update them.
2. We should include the brief cohort descriptions as new API endpoints, similar to the Terms of Service endpoint. However, unlike the Terms of Service endpoint, I think we should include the cohort description that is specific to each ICEES instance (e.g., asthma).
3. We should replace the "Documentation" link within the Swagger UI with a link to the description of feature variables and binning strategies, perhaps as a new file within GitHub. I suppose we could create a new endpoint for feature variables, too, but it seems like the easier solution is to simply point to the documentation.
4. The ICEES Overview page was created using markdown, so we can probably add it to the API repo and point to it from the Swagger UI. Of course, I should probably first update a few outdated items.

Thoughts?

[hyi]

@karafecho All sounds good to me. My response to your thoughts are below:

1. We should maintain the documentation within the G-folder as "living docs", so that we can more readily update them.

Right, "Living docs" is necessary to keep documentation up to date, but my preference is to have the documentation in the same repo either as markdown file or pdf file, but I can see your point to have it live in the G-folder for easier update. As long as it is linked out from Swagger UI, it should be fine.

2. We should include the brief cohort descriptions as new API endpoints, similar to the Terms of Service endpoint. However, unlike the Terms of Service endpoint, I think we should include the cohort description that is specific to each ICEES instance (e.g., asthma).

Alternatively, if cohort description serves as documentation not specific to a dynamically created cohort, it might be better to include it as part of the documentation or just include a cohort description link to get it stand out rather than creating a new endpoint. I'll defer to you to see which way works better for users from user perspective.

3. We should replace the "Documentation" link within the Swagger UI with a link to the description of feature variables and binning strategies, perhaps as a new file within GitHub. I suppose we could create a new endpoint for feature variables, too, but it seems like the easier solution is to simply point to the documentation.

Agreed. I think we should only create a new endpoint when it is absolutely necessary. In other words, we should not use endpoints to return documentation related content, but to only return data and analysis results.

5. The ICEES Overview page was created using markdown, so we can probably add it to the API repo and point to it from the Swagger UI. Of course, I should probably first update a few outdated items.

Sounds good.

[karafecho]

Thanks for your comments, @hyi.

Re (1), I am fine with storing the documentation in the repo. In fact, I had deposited a pdf file a while back, but Patrick Wang removed it for organizational purposes, I believe. I pulled a few new exposures datasets this morning and will update the documentation before adding it to GitHub.

Re (2) and (3), I agree. Let's add/update the documentation links in the Swagger UI.

Re (5), I'll update the markdown file.

[karafecho]

Closing tickets, as issue has been resolved.