GSoD 2020 - OpenMRS REST API Documentation

@burke thanks alot for the valuable feedback. I would agree on the priority of the list and it make sense to move forward on that way.

@saurabh I would suggest you to do the changes burke mentioned. Let’s publish it as soon as the changes are done.

Also great work on bringing up the survey so fast. Nice work @saurabh

1 Like

@burke @ayesh I am bit unclear about #3, #4

I get #2, we would dive deep into those basic resources and try to get as close to the ideal documentation as possible .

Then I am a bit unsure what do we do in #3 and #4, try and get those changes incorporated in the swagger auto generated documentation by editing the OpenAPI spec or any anything else I dint get ? or try and expand the work done to other resources.

Then in #5 we embed the auto-generated documentation (after going through #3 and #4) in our static documentation which would even give us a try-out-feature in our static documentation.

I think the current Swagger documentation may be built through real-time queries to the API. While this sounds like the coolest & most robust approach to ensuring resources are properly represented, the reality leaves a lot to be desired. First, there’s an undesirable delay to regenerate the documentation every time it’s referenced, making the real-time generation less than ideal. Secondly, the auto-generated properties are often not what we’d want (e.g., all the details for a location instead of just the UUID as reference). Lastly, the datatypes are under-specified and description are lacking in many/most cases.

That said, I was hoping/expecting that we could use a Swagger/OpenAPI tool to generate an OpenAPI document from comments/annotations in the code. If true, then the task ahead would be to go through those annotations/comments and populate them so we can generate documentation similar to #2.

1 Like

I will do a bit of research about it and see how would it work but currently I will add these to the google form :slight_smile:

1 Like

@saurabh yes when moving forward let’s try to find a way and do it together. For now, let’s get feedback from the community.

1 Like

the survey is up :smiley:

nice :smiley:

cc :- @jennifer @grace @herbert24 we need some help here to get responses to the survey.

Good job, @saurabh. I made a few tweaks to your post. I hope that’s okay. :slight_smile:


@ayesh @burke,

just a thought since we find it difficult to make examples that actually work at an instance since sometimes the UUID used in the examples arent present on the server.

  1. we can shift the create Resource section above the list resource section in every resource heading and that way we would be able to use the UUID of the created resource for listing, editing and deleting .

  2. sometimes in complex resources there is a requirement of other resources’ UUID as well, in this case we might need to make some resources read-only on the server so that they cant be deleted and can be used in the examples safely.

(I have seen instances of such resources while creating examples for system setting here and I had mentioned there that we must create our own system setting in order to modify it because some of them are read-only)


I would suggest using UUIDs for data provided in the default demo dataset. The demo dataset SQL is here. The easiest way to play with the demo data at the moment is to use Docker:

  1. Copy this docker-compose.yml file into a local folder,
  2. Place this SQL file into a dbdump subfolder
  3. Type docker-compose up -d in the original folder (containing the docker-compose.yml file)

Within a few minutes, you should have OpenMRS with demo data starting up locally at http://localhost:8080/openmrs/ and, when it’s done, you can login using admin/Admin123 credentials. You can also test the API using httpie:

$ http localhost:8080/openmrs/ws/rest/v1/session
HTTP/1.1 200 OK
Content-Length: 70
Content-Type: application/json;charset=UTF-8
Date: Fri, 28 Aug 2020 15:49:38 GMT
ETag: "0c4da90337cfeb79674b823f8e4c42e47"
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=A5CD4820FD7BBD22ECC1DFC58758E49C; Path=/openmrs; HttpOnly

    "authenticated": false,
    "sessionId": "A5CD4820FD7BBD22ECC1DFC58758E49C"

p.s. You can stop and start OpenMRS with docker-compose stop and docker-compose start (takes a few minutes to restart). You can clean up (remove everything) with docker-compose down -v (you’ll have to go through full initialization process the next time you bring it up).

1 Like

@burke I will try setting this up thanks :slight_smile:.

if developers try these examples on the demo -server will these examples still work? since I think people can purge some of the resources present on the server.

tl;dr true, but I wouldn’t worry about it

Correct, but I don’t think this is a big enough problem to worry about. If we end up with issues of people routinely purging data on the demo server, we can either try pointing our examples to different resources (e.g., if we happened to pick resources that are more commonly purged on demo) or consider making some data read only on demo. I don’t think this is going to be enough of an issue to warrant the effort.

A more likely issue is demo being down, but I think that will be less of a problem over time as we improve our dockerization and by adapting demo to use an image that has already performed initialization.

1 Like

So I had a look on the demo server compose file it seems like we dont have a volume attached to the demo server mysql which means basically in everystartup We start with brand new database with out the previous data that was created by users.

Am not sure the reason for this is there any specific reason @burke?

This is by design. The demo server is for demonstration. People play with it and the data are reset daily.

@ayesh @burke I was looking throught this post here and got something for fiddling with the swagger based documentation here. is it still relevant for our project ?

Hi @saurabh

No I think it was back in 2015 before generating the swagger docs with try out options.

1 Like

Correct. The auto-generation of Swagger documentation is a cool idea but has two problems: (1) generating at runtime means you have to wait for documentation to be generated every time you reference it and (2) there are a lot of gaps in the auto-generated documentation (many properties labeled as a “string” with no description or examples and a lack of any high level documentation to tell you when/why to use resources, tips for best practices, etc.).

Ideally, we’d use an auto-generation approach like this at build time to automate parts of our static documentation (e.g., “try it out” examples) and to highlight where our manual documentation might be misaligned or out of date with changes in the code.


@burke @ayesh are there any significant differences between when should we use the term sub-resouces and when should we use the term metadata-types. here I read that we use the term metadata-types for things we describe as sub-resources in our RestAPI docs ?

Subresource is a technical term for properties of a resources that are themselves surfaced as separate resources. The term “subresource” may be useful for people developing the the REST API, but I think the term is confusing to people consuming the API and would prefer that we not use it so much in our documentation.

Metadata could be thought of as “data about data” or “supporting data” or “system data”. Examples may help:

Data Metadata
Bob is right-handed. A person can be right-handed, left-handed, or ambidextrous.
Eve’s temperature is 37°C Temperature is measured in centigrade and can be between 25 & 43
Wyclif’s encounter in Clinic A The hospital has clinics: Clinic A, Clinic B, and Clinic C

Trying to say it another way, data are information about a patient and metadata are information about the data we collect. The supporting information of encounter types, concepts, locations, etc. are types of metadata. The information we collect about patients (observations, encounters, notes, etc.) are data. When you are looking at the data model, you’ll see data can be deleted (voided); metadata cannot be deleted once used (if you recorded encounters at a location last week, deleting the location would invalidate all those data), but metadata can be retired to keep it from being used going forward (when a concept, location, or other metadata are retired, it means it should no longer be used but does not invalidate any data previously collected using those metadata).


thanks alot @burke