Buendia REST API Spec

Out of date

Note: this is out of date as a result of recent sync changes. Tracking issue: #32

Summary

This document contains the Buendia REST API specification. Throughout the document a specific syntax is used to compactly describe a family of possible URLs. This syntax is defined as follows:

Syntax	Meaning
{x}	x is a variable
[x]	x is optional
x,...	x is a comma-separated list

Endpoints

Basic information about each endpoint supported by the Buendia server are listed below; for more details about each one, consult the Javadoc for the corresponding Resource class.

• Resource: the class responsible for handling the request; all resource classes are contained in the org.openmrs.projectbuendia.webservices.rest package
• Method: the HTTP method
• Endpoint: the URL path; prefix this with http://server:9000/openmrs/ws/rest/v1/projectbuendia to form the complete URL
• Description: the operation performed

Resource
Method	Endpoint	Description
ChartResource
GET	/charts[?v=full]	Returns the existing chart definitions (stored as OpenMRS Forms on the server). Without `?v=full`, just returns the name and version number of each chart; with `?v=full`, returns the complete definition of each chart.
GET	/charts/{UUID}[?v=full]	Returns the chart definition with the given UUID. Without `?v=full`, just returns the name and version number of the chart; with `?v=full`, returns the complete definition of the chart.
ConceptResource
GET	/concepts[?locales={en,...}]	Returns every concept that is present in at least one form.
GET	/concepts/{UUID}[?locales={en,...}]	Returns the concept with the given UUID.
LocationResource
GET	/locations	Returns all locations.
GET	/locations/{UUID}	Returns the location with the given UUID.
POST	/locations	Creates a new location. Warning: This endpoint is not well tested.
POST	/locations/{UUID}	Updates the location with the given UUID. Warning: This endpoint is not well tested.
DELETE	/locations/{UUID}	Deletes the location with the given UUID. Warning: This endpoint is not well tested.
PatientEncountersResource
GET	/encounters[/{UUID}]	Returns all patient encounters, or the patient encounter with the given UUID.
POST	/encounters	Creates a new patient encounter. Ideally, patient encounters should be created by XForm submissions, but this endpoint allows clients to circumvent using XForms. WARNING: the data format for posting observations is different from the data format in which observations are returned. (This needs to be fixed; see the source code for more details.)
PatientResource
GET	/patients[?q={query}]	Returns all patients, optionally filtering by a search term. If a search term is provided, the server performs a substring search on the patient's full name.
GET	/patients[?id={ID}]	Returns the patient with the given ID, if there is such a patient.
GET	/patients/{UUID}	Returns the patient with the given UUID.
POST	/patients	Creates a new patient.
POST	/patients/{UUID}	Updates the patient with the given UUID.
UserResource
GET	/users[?q={query}]	Returns all users, optionally filtered by a query term. If a query term is provided, the server will perform a substring search on the user's full name.
GET	/users/{UUID}	Returns the user with the given UUID.
POST	/users	Creates a new user.
XformInstanceResource
POST	/xforminstances	Submits a filled-in XForm.
XformResource
GET	/xforms[/{UUID}][?v=full]	Returns all forms, or the form with the given UUID.

Possible outcomes

HTTP Code	Used in situation where
200 OK	the request was correct and successful
201 Created	a POST request to create a resource was successful
400 Bad Request	the request contained unknown parameters or illegitimate values
401 Unauthorized	user could not be authenticated
403 Forbidden	user was authenticated but the server will not authorize the request
404 Not Found	the request referred to an unknown entity
405 Method Not Allowed	the HTTP method used is not supported by the requested endpoint
500 Server Error	the request caused an unexpected error