# GSoD 2019: Improved REST API Documentation **URL:** \ **Category:** Google Season of Docs\ **Tags:** gsod2019\ **Created:** [August 15, 2019, 3:49am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328 "2019-08-15T03:49:35Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![burke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/burke/32/17_2.png) [@burke](https://talk.openmrs.org/u/burke)\ **Post date:** [August 15, 2019, 3:49am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/1 "2019-08-15T03:49:35Z")
@ayesh & @batbrain7, please take a look at [5 Examples of Excellent API Documentation (and Why We Think So)](https://nordicapis.com/5-examples-of-excellent-api-documentation/) and [7 Items No API Documentation Can Live Without](https://nordicapis.com/7-items-no-api-documentation-can-live-without/). I’m far less interested in another round of Swagger documentation tweaks producing variations on [this](https://petstore.swagger.io/), where pretty colors, rounded boxes, and interactive “documentation” get prioritized over descriptive content. What the OpenMRS community really needs is clean & concise, well-written documentation of our REST API that targets both introduction (for those new to the API) and reference (for those looking for details on a part of the API they haven’t used lately). We also need to keep things simple, since it’s important to produce something that can be maintained. There are several documentation generators around we could consider; just [ask google](https://www.google.com/search?q=static+documentation+generator) or find lists [like this](https://github.com/myles/awesome-static-generators#documentation)… but I’d be fine to start with simple Markdown. These are the types of things that I’m thinking about regarding REST API documentation: - Use Markdown - Prioritize concise, pragmatic, descriptive content (e.g., teach someone how to authenticate to the REST API in a few minutes, explain what’s working for orders and what isn’t). - Support syntax highlighting, since good examples are priceless - Avoid the shiny/attractive niche tool that might be abandoned in 1-2 years - Search, table of contents, support for translations of the API are nice-to-haves, but lower priority than having quality content. - We’ll want to create a backlog (prioritized list of things to document) and then divide & conquer. Cheers, -Burke :burke: ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 15, 2019, 8:11am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/2 "2019-08-15T08:11:23Z")
Hi @burke Just a one thing to clarify.From the two projects descriptions of mine and @batbrain7 I kind of feels that we both are working on a joint project am I right. Thank you Ayesh ---
**Author:** ![burke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/burke/32/17_2.png) [@burke](https://talk.openmrs.org/u/burke)\ **Post date:** [August 15, 2019, 1:29pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/3 "2019-08-15T13:29:56Z")
> [@ayesh](#): > > Just a one thing to clarify.From the two projects descriptions of mine and @batbrain7 I kind of feels that we both are working on a joint project am I right. Correct. We defined one project to improve our REST API documentation, both of you applied to work on that project, and both were accepted by GSoD. So, we’ll work as a team to divide & conquer. This can be very good news, since we have no shortage of REST API endpoints to document. 🙂 ---
**Author:** ![tendomart](https://talk.openmrs.org/user_avatar/talk.openmrs.org/tendomart/32/6753_2.png) [@tendomart](https://talk.openmrs.org/u/tendomart)\ **Post date:** [August 15, 2019, 1:30pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/4 "2019-08-15T13:30:48Z")
> [@ayesh](#): > > Just a one thing to clarify.From the two projects descriptions of mine and @batbrain7 I kind of feels that we both are working on a joint project am I right. > > Thank you Ayesh Yes you are ,but i think you will be handling different sections given the magnitude of the work. ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 15, 2019, 1:36pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/5 "2019-08-15T13:36:48Z")
Hi @burke @tendomart Yes that is an excellent decision.✌.Awesome 😃.I think it will be great to have a call and discuss about our next steps after we go through the materials that @burke mentioned am I right @batbrain7. Regars Ayesh ---
**Author:** ![batbrain7](https://talk.openmrs.org/user_avatar/talk.openmrs.org/batbrain7/32/10171_2.png) [@batbrain7](https://talk.openmrs.org/u/batbrain7)\ **Post date:** [August 20, 2019, 10:38am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/6 "2019-08-20T10:38:41Z")
Sorry for the late reply. Definitely @ayesh, We’ll sync up and work on it as a team. ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 20, 2019, 10:48am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/7 "2019-08-20T10:48:00Z")
Awesome 😃✌ ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 22, 2019, 5:05pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/8 "2019-08-22T17:05:22Z")
Hi @burke , @batbrain7 , @tendomart This seems to be a good option for us [https://lord.github.io/slate/#introduction](https://lord.github.io/slate/#introduction) > **[lord/slate](https://github.com/lord/slate)** > > Beautiful static documentation for your API. Contribute to lord/slate development by creating an account on GitHub. what do u guys think 😃 ---
**Author:** ![tendomart](https://talk.openmrs.org/user_avatar/talk.openmrs.org/tendomart/32/6753_2.png) [@tendomart](https://talk.openmrs.org/u/tendomart)\ **Post date:** [August 23, 2019, 1:57pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/9 "2019-08-23T13:57:10Z")
I think it’s good considering the Scope , can we also look at these options (ofcourse leaving out swagger and others smilar ) > **[Free and Open Source API Documentation Tools](https://pronovix.com/blog/free-and-open-source-api-documentation-tools)** > > We explored free and open source API documentation solutions, and compiled the results of our research in this post. ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 24, 2019, 8:26am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/10 "2019-08-24T08:26:39Z")
Hi @tendomart Sure will have a look on them.And I think it wil be good of we can have both mark down and try out options if am right as @burke mentioned in a previous thread. ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 24, 2019, 8:31am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/11 "2019-08-24T08:31:59Z")
These below two options seems to be intresting [https://rebilly.github.io/RebillyAPI/#operation/GetCustomerTimelineCustomEventTypeCollection](https://rebilly.github.io/RebillyAPI/#operation/GetCustomerTimelineCustomEventTypeCollection)[http://apidocjs.com/example/](http://apidocjs.com/example/) ---
**Author:** ![gcliff](https://talk.openmrs.org/user_avatar/talk.openmrs.org/gcliff/32/8783_2.png) [@gcliff](https://talk.openmrs.org/u/gcliff)\ **Post date:** [September 3, 2019, 7:33am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/12 "2019-09-03T07:33:06Z")
Hello 🤚 @ayesh and @batbrain7 hope things are going on well with the project that you are working on ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [September 3, 2019, 7:52am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/13 "2019-09-03T07:52:17Z")
Hi @gcliff Currently we didn’t had a call with @burke.But we have few paths identified.And am currently thought of working with [https://rebilly.github.io/RebillyAPI/](https://rebilly.github.io/RebillyAPI/) redoc. Had to get ideas about it from @burke ---
**Author:** ![gcliff](https://talk.openmrs.org/user_avatar/talk.openmrs.org/gcliff/32/8783_2.png) [@gcliff](https://talk.openmrs.org/u/gcliff)\ **Post date:** [September 3, 2019, 8:12am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/14 "2019-09-03T08:12:19Z")
THANKS @ayesh for the feedback and am sure @burke will respond as soon as this comes to his notice ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [September 3, 2019, 8:06pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/15 "2019-09-03T20:06:14Z")
Hi @burke Will it possible to have a call to discuss about the projects 1. As far as I understand and as gsod project page says I have to develop the github like documentation project.I would like to prefer [ReDoc](https://rebilly.github.io/RebillyAPI/#section/Getting-Started-Guide) as the template to use it’s interactive by the nature as well. ---
**Author:** ![tendomart](https://talk.openmrs.org/user_avatar/talk.openmrs.org/tendomart/32/6753_2.png) [@tendomart](https://talk.openmrs.org/u/tendomart)\ **Post date:** [September 4, 2019, 3:00pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/16 "2019-09-04T15:00:26Z")
I sent @burke so that we should wait for him and see schedule and find out when is the best time to meet him. In the mean time are you folks\*(@ayesh , @batbrain7) familiar with the currently available REST API Documentation Structure. ---
**Author:** ![burke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/burke/32/17_2.png) [@burke](https://talk.openmrs.org/u/burke)\ **Post date:** [September 5, 2019, 5:11am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/17 "2019-09-05T05:11:25Z")
Hey. Sorry for the delay in response. I am traveling over the next few days and attending a conference, so my schedule is difficult to predict. My top priority for this project is concise, well-written text to help devs understand how to use the API. Using a tool like ReDoc is fine; however, I’d rather have a handful of well-written, concise, helpful descriptions of key API methods written by humans for humans than to see more “documentation” [like this](https://docs.discourse.org/#tag/Web-Hooks%2Fpaths%2F~1admin~1api~1web_hooks%2Fpost). To be clear, I do not consider a pretty interactive interface for a REST endpoint with a description like “Create an encounter.” as adequate documentation (in fact, I see it as a failure to document). If choosing between interactive documentation with auto-generated descriptions of methods like “Get a foo” or “Create a foo” vs. a paragraph or two explaining how to use a resource (e.g., that one of the GSoD students wrote after interviewing a few devs and testing the API with Postman or HTTPie) with a static example, I’d take the latter every time. If I were to prioritize goals it would be something like this: - Concise, well-written descriptions of how/when to use a resource based on examining the code and interviewing devs. - The beginning of documentation similar to [GitHub API documentation](https://developer.github.com/v3/) (not referring to the specific format/tooling; rather, the content & ease of reading/understanding) - Descriptions written in a simple format. While we could use the wiki, I’d personally prefer using simple Markdown, since it’s more portable. - A prioritized outline of what we’ll document. I’m less interested in a list of every known resource and more interested in what the first ~20 items we’ll focus on (e.g., introductory sections and then key resources). There’s some decent content [here](https://wiki.openmrs.org/x/P4IaAQ); though, it’s a bit dated. Hopefully this can provide some context of what I’d like us to accomplish. Forgive me for not being able to schedule a call at the moment. We may be able to find a time for a call soon; however, in the meantime, let’s try to make due with asynchronous communication here. ---
**Author:** ![dkayiwa](https://talk.openmrs.org/user_avatar/talk.openmrs.org/dkayiwa/32/179_2.png) [@dkayiwa](https://talk.openmrs.org/u/dkayiwa)\ **Post date:** [September 5, 2019, 8:24pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/18 "2019-09-05T20:24:27Z")
Just sharing an example where our documentation needs improvement: [Creat new REST endpoints in my module](https://talk.openmrs.org/t/creat-new-rest-endpoints-in-my-module/24622) ---
**Author:** ![herbert24](https://talk.openmrs.org/user_avatar/talk.openmrs.org/herbert24/32/8178_2.png) [@herbert24](https://talk.openmrs.org/u/herbert24)\ **Post date:** [September 9, 2019, 7:30am UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/19 "2019-09-09T07:30:17Z")
cc @jwnasambu@c.antwi ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [September 9, 2019, 6:53pm UTC](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328/20 "2019-09-09T18:53:27Z")
Hi @burke I went through the API list as a start, as well as the content, provided [REST Web Services API For Clients](https://wiki.openmrs.org/display/docs/REST+Web+Services+API+For+Clients) Bit confused about where to get started how to separate the work between two of us. Shall I start on making something similar for GitHub API documentation web site? [Next page](https://talk.openmrs.org/t/gsod-2019-improved-rest-api-documentation/24328.md?page=2)