GSoD 2019: Improved REST API Documentation

Tags: #<Tag:0x00007f29926cf788>

@ayesh & @batbrain7, please take a look at 5 Examples of Excellent API Documentation (and Why We Think So) and 7 Items No API Documentation Can Live Without.

I’m far less interested in another round of Swagger documentation tweaks producing variations on this, 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 or find lists like this… 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:

3 Likes

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

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. :slight_smile:

2 Likes

Yes you are ,but i think you will be handling different sections given the magnitude of the work.

1 Like

Hi @burke @tendomart

Yes that is an excellent decision.:v:.Awesome :smiley:.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

1 Like

Sorry for the late reply. Definitely @ayesh, We’ll sync up and work on it as a team.

1 Like

Awesome :smiley::v:

Hi @burke , @batbrain7 , @tendomart

This seems to be a good option for us

https://lord.github.io/slate/#introduction

what do u guys think :smiley:

I think it’s good considering the Scope , can we also look at these options (ofcourse leaving out swagger and others smilar )

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.

These below two options seems to be intresting

https://rebilly.github.io/RebillyAPI/#operation/GetCustomerTimelineCustomEventTypeCollection http://apidocjs.com/example/

Hello :raised_back_of_hand: @ayesh and @batbrain7 hope things are going on well with the project that you are working on

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/ redoc.

Had to get ideas about it from @burke

THANKS @ayesh for the feedback and am sure @burke will respond as soon as this comes to his notice

1 Like

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 as the template to use it’s interactive by the nature as well.

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.

1 Like

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. 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 (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; 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.

2 Likes

Just sharing an example where our documentation needs improvement: Creat new REST endpoints in my module

cc @jwnasambu @c.antwi

1 Like

Hi @burke

I went through the API list as a start, as well as the content, provided 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?