GSoD 2019: Improved REST API Documentation

Community Google Season of Docs
45

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