GSoD 2019: Improved REST API Documentation

Thanks , @c.antwi can you please share a link to the conference recording here ?

Hi @burke , @dkayiwa , @ssmusoke

I faced a small issue when trying to execute API from the swagger UI.

curl -X GET “https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/app?limit=1&startIndex=2&v=full” -H “accept: application/json”

is this endpoint open? Means can we execute them without basic auth header?. Because without the header I was able to get results.

I can see in the swagger response codes it has user not logged in not authorized code as well.And in the wiki it says all endpoints except /session endpoints are secured.

Hi @burke , @dkayiwa , @ssmusoke , @mozzy

I am trying to get an idea about the encounters as far as I know when a patient visits a health center or hospital. For each electronic form completed for a patient, a new encounter is created.

And encounters can be of two types

  1. Location encounters
  2. Patient encounters

To find out the encounter belongs to a specific patient if am right I should send a get request to like below with the uuid of the patient.

curl -X GET \
  'https://demo.openmrs.org/openmrs/ws/rest/v1/encounter/fc6ee64e-9f64-4213-8716-ae0ba93bb71d/encounterprovider?limit=1&startIndex=0&v=full' \
  -H 'Authorization: Basic YWRtaW46QWRtaW4xMjM=' 

But am receiving an error message like below. Any idea about it

https://pastebin.com/8Q4MVV9R

Are these resources of help?

https://guide.openmrs.org/en/Getting%20Started/openmrs-information-model.html

2 Likes

Hi @dkayiwa

Thank you this will help alot :slightly_smiling_face:

@ayesh and team, is this also something that you are going to address with documentation? Reference Application 3.0 - Where do we go from here?

In general, the only endpoints supporting anonymous requests should be those required for authentication. Sites can make other features accessible (e.g., sharing their concept dictionary), but this example looks like a method that should require authentication, but is not. Unfortunately, this is exactly why we need REST API Documentation – i.e., what is an “app”? Should you be able to get information about them anonymously?

@dkayiwa, thoughts? Does /app need to be available to anonymous users in order to get to a login screen?

$ http -a admin:Admin123 'https://demo.openmrs.org/openmrs/ws/rest/v1/encounter/fc6ee64e-9f64-4213-8716-ae0ba93bb71d&v=full' | jq -r '.error.message'
Object with given uuid doesn't exist [null]

I don’t know where you got the encounter UUID, but it appears to not exist. If I find a patient via:

$ http -a admin:Admin123 'https://demo.openmrs.org/openmrs/ws/rest/v1/patient?q=Taylor
' | jq -r '.results[0]'
Response
{
  "uuid": "90f7f0b4-06a8-4a97-9678-e7a977f4b518",
  "display": "10010W - John Taylor",
  "links": [
    {
      "rel": "self",
      "uri": "http://demo.openmrs.org/openmrs/ws/rest/v1/patient/90f7f0b4-06a8-4a97-9678-e7a977f4b518"
    }
  ]
}

And then search for encounters for that patient:

$ http -a admin:Admin123 'https://demo.openmrs.org/openmrs/ws/rest/v1/encounter?patient=90f7f0b4-06a8-4a97-9678-e7a977f4b518'
Response
{
    "results": [
        {
            "display": "Vitals 25/08/2015",
            "links": [
                {
                    "rel": "self",
                    "uri": "http://demo.openmrs.org/openmrs/ws/rest/v1/encounter/1d2bdaf3-2a70-4035-844b-bbbb42cb666e"
                }
            ],
            "uuid": "1d2bdaf3-2a70-4035-844b-bbbb42cb666e"
        },
        {
            "display": "Visit Note 25/08/2015",
            "links": [
                {
                    "rel": "self",
                    "uri": "http://demo.openmrs.org/openmrs/ws/rest/v1/encounter/3960550c-d25c-441f-ae87-debeff8924e3"
                }
            ],
            "uuid": "3960550c-d25c-441f-ae87-debeff8924e3"
        },
        ...
    ]
}

And then request one of those encounters:

$ http -b -a admin:Admin123 'https://demo.openmrs.org/openmrs/ws/rest/v1/encounter/1d2bdaf3-2a70-4035-844b-bbbb42cb666e?v=full'

See large response on pastebin.

1 Like

Oh okays @burke

I created the patient for my reference but this way it’s working fine thank alot.

I do not believe so. Apps are accessed only after log in.

@dkayiwa

Can u access this on incognito mode

https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/app?limit=1&startIndex=2&v=full

Hi @burke @dkayiwa

Is Orderentry ui still in usage? When I configured that to run with the latest ref app I can only see the prescribed medication link which points to the owa app (orderentry owa) .

But In a thread related to drug management saw the usage of orderenrty ui as well.Is there any configuration am missing (thread :- Drug Management)

I just want to get an idea about orders in the meantime thought to check the responsiveness of the orderentryui as well that’s why.But anyhow when I try to access it manually with typing the url I can access the module.

@ayesh my thinking was that you are starting with your focus on the resources provided by the webservices module.

Hi @dkayiwa

As per the discussion with @burke last Friday started things off things with already existing document and to refine them because they were outdated.On REST+Web+Services+API+For+Clients.

This is why I was testing the orders in Orderentry ui module in order to get an idea about subtypes because orders have test and drug order types.

And then move forward with resource types and build something like this.

And this is the place where we keep next upcoming tasks suggestions by @burke.

Hi @shafiq12

That is great to hear that you are intrested in working with us. :slightly_smiling_face: And this will be the talk thread for the project.

We are (Me an @batbrain7) currently focusing on Visits , Location , Encounter , And Patient Resource types.

The next resources we will work on will be here

As it shows u can pick up concepts resource type and move forward.It will be great.

Resources for u to refer

OpenMRS API docs :- https://psbrandt.io/openmrs-contrib-apidocs/

OpenMRS Swagger documentation:- https://qa-refapp.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm

OpenMRS Data model :- https://docs.openmrs.org/datamodel/

And u can intreact with the endpoints and get how there used by refering the OpenMRS Reference application server hosted here

First we will be working on mark down documentation.One markdown file for one resource.

You can find the repository that we are working here .

Fork it and make sure to send a PR when u are finished working on a resource.And let know if there are any problem for u to get started

Thank you Ayesh

Hi @burke @dkayiwa @tendomart

I have a small question regarding the below endpoint.Where we can query to get visit details.

    curl -X GET "https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/visit?limit=1&startIndex=0&v=default&q=11" -H  "accept: application/json" -H  "authorization: Basic YWRtaW46QWRtaW4xMjM="   

What type of search query this endpoint accepts(value for q query parameter). I tried with patient name, display attributes a visit has but I didn’t get any result.

Did you see my examples above? Have you tried patient=:UUID instead of q=something?

Hi @burke

Yes I tried with uuid it works.But I am currently writing about this endpoint so just want to get an idea from what a visit can be searched :slightly_smiling_face:

Yeah. You’ll need to look at code or ask some devs.

@ayesh & @batbrain7, I’ve added some tips to our shared google doc. I’d like to adopt some consistent conventions in the documentation. While having some directly useable (copy & paste) examples of working curl commands (probably using demo.openmrs.org) could be instructive for n00bs, there’s a lot of unnecessary text we could avoid repeating with some simple conventions. For example, curl commands & parameters, base URLs, etc. We also want to minimize horizontal scrolling when possible in examples.

Also, don’t we want to put our documentation under a folder (e.g., docs/) in the repo with subfolders based on sections?

Finally, my initial notes in the google doc where just some examples of the types of things that we might want to start with. I’d like you to draft an outline (e.g., table of contents) of the sections you think we should tackle in our first pass (not a list of every resources, but the sections you think we should include up front followed by some of the key services/resources organized in whatever hierarchy you propose).

1 Like

@ayesh as for the visit search options, is this helpful? https://github.com/openmrs/openmrs-module-webservices.rest/blob/master/omod-1.9/src/main/java/org/openmrs/module/webservices/rest/web/v1_0/resource/openmrs1_9/VisitResource1_9.java#L322-L325

1 Like

Hi @dkayiwa

Yes sure it helps.

But the problem is as I saw in the code as well in the request context it’s searching for location,patient,includeInactive,fromStartDate parameters.

curl -X GET  'https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/visit?limit=1&v=default&includeInactive=true&patient=0a13a870-b9c8-4f07-be5f-ca8398a4cd8d&location=8d6c993e-c2cc-11de-8d13-0010c6dffd0f'  -H 'Authorization: Basic YWRtaW46QWRtaW4xMjM=' 

But in swagger documentation, it’s saying it requires q as shown in screen shot (query param). Is it possible or only we can search like above curl request?.