GSoD 2020 - OpenMRS REST API Documentation

Thank you @herbert24 i will look through them :slight_smile:

1 Like

Interesting. So, this seems to confirm my assumption that people like concise, descriptive documentation (like GitHub’s docs) and would like to see it more comprehensive (covering more resources and including modules that extend our REST API).

I’m still advocating this approach:

  1. Get 1-3 resources documented manually to the point where everyone agrees “we want more of THAT!”
  2. In parallel:
    • Begin fixing & expanding documentation to match the “gold standard” in #1
    • Decide on the best mechanism (for now… avoid getting stalled waiting for perfect) to generate that documentation. How much can we generate from code? How can we limit the amount of documentation needed outside of the code? How can we accommodate modules that extend our REST API?

While I think the ideal solution would be most of the static documentation (except some manually managed text for intro/overview/auth/contributing) generated automatically by a Swagger-like tool grepping our code (including modules) with gaps filled by well-written annotations/Javadocs in the code, I don’t think figuring out the technical solution is a good use of GSoD. We need decent descriptions, examples, etc. whether they are written manually into a GitHub repo or placed in the code… we can always copy & paste them elsewhere in the future if needed.

1 Like

@ayesh I have made few changes to the project timeline (In the project proposal) as @burke suggested,

So I will be working on resources ie patient,encounter,visit and obs for making them better and in parallel, I would be fixing and patching other parts of the documentation with examples and additions. when we would be ready with these 4 resources we can have a small review of these resources and then move forward with expanding this standard to other resources as well.

@ayesh I would edit the flow if you have some changes to suggest :slight_smile: !!

@ayesh @burke can I rely on this data model doc to annotate the current resource attributes with required tags?

Hi @saurabh

I would say yes but cross-check it with the swagger

1 Like

Hi @burke

Yes I like that approach.

So what are the first 3 resources we are going to document.

I believe it’s best to get developers input for the documentation. Will it work if we go with another survey to identify missing points. Or direct messages may be a new talk thread where all dev people can give their opinion would work ?

There are a few ways to approach this…

a. Pick a few key resources

Take 2-3 resources that have high value & test different aspects of our documentation needs. For example:

  1. authentication - something everyone needs to be able to do
  2. obs – the key clinical data resource
  3. concept – an example of complicated metadata

b. Focus on a few resources people are asking about

Search Talk for examples of people struggling with the REST API like here, here, and here and focus on those resources.

c. Watch people try to use the REST API

Find a couple people who are familiar with OpenMRS and it’s data model, but who have never used the REST API, and record sessions of them trying to do some specific operations using the REST API (e.g., find a patient, register a patient, create a new concept for a fake lab test, record an encounter for the registered patient containing a result for the fake lab test).

With a & b, while you could requests the community to review & comment, but we’d want to enlist at least one n00b, one /dev/2, and one expert to review the documentation and make suggestions. It would probably be easiest for them to schedule a 30- or 60-minute call where they share their screen and read through the documentation and give you feedback. An alternative (or additional option) would be to convince/urge some developers who are doing active development to try using the documentation and then give you feedback on their experience.

With c, the person’s successes & challenges trying to learn & use the REST API would point out its strengths and weaknesses.

1 Like

@ayesh @burke I am starting working on these resources, as you mentioned and will get back for feedback and suggestions.

1 Like


  1. what should we use for adding JavaScript examples jquery based vs fetch based I dont know which one would be better . I will update the getting started guide accordingly !!

  2. should we add responses for all restAPI calls that we have or some specific ones ?

Hi @saurabh

Shall we first finish Java Examples?. Adding examples in the current form is easy. But we have to focus on what @burke mentioned here.

1 Like

yes Sure @ayesh I was going to add all the examples for the resources burke mentioned so that they are complete in that aspect also for other resources I am not currently starting javascript examples

@ayesh in the auth section when we are able to retreive a session token after authentication then how do we use it with subsequent requests to other endpoints,

as of now I am sending the basic auth header with each of my requests is it possible to do the other way around as well using the session token ?

Hi @saurabh, no, currently, only the basic auth is what in place. Anyway, few modules were coming up with the support of session tokens. For example, keycloack IDP based solutions that are coming up for enterprise-level openMRS integrations, which federates openMRS user base to keycloak and perform authentication and authorization based on oauth2 and OpenID connect. Which will give us a session token where we can perform authorization based on that token with the help of OIDC. But for now we don’t have to worry about it.

1 Like

ok @ayesh I will just add one basic auth example in that section and leave the jsession token part for now !!

@ayesh I need some help in the last section of the auth resource in this PR could you look at my comments :slight_smile:

1 Like

hi @ayesh do you have some time to help me look through this task on the trello board cc @burke

he has done it already @herbert24 for my current trello tasks !! :slight_smile:

Hi @saurabh

I merged youre pr.Now lets focus on what @burke mentioned.I saw u have created a draft pr for concept.Looks good.

Can we find few talk posts where developers or new comers found problematic to use the authentication in openmrs ? As a start point ?


Actually @ayesh I have made a list of those talk posts and I am going to remove all those issues in the 3 resources that burke pointed out.

I am done with authentication and currently working on concept section . also I am trying to encorporate all those changes which burke deemed as minimum requirement for each resource here

after I am happy with the current state of these three resouces then we can have a reveiw or a survey again of these theree resources while in parallel I will continue working on other resources and get back to these resources after getting feedback from people

Great man.Please share the links in the thread so we can get @burkes opinion as well.

Good work done so far keep it up

1 Like

sure @ayesh I will be linking all my PRs here and in trello as I am doing :+1: