Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Documentation

Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Conventions

TODO: copy from Web Services API (Design Page) once it is finalized

When saving or editing a property on a "Concept" object, the conceptDatatype property can be simply the uuid. In addition, for most metadata, the "name" is unique across all active metadata, so that can also be used in place of the uuid when saving as well (POST or PUT).

Representations

The objects returned by web service calls are variable in their properties. In general there are three different representations that exist: ref, default, full. It is possible for modules to provide more representations for their objects. (TODO: document what method to call to get the available reps)

To change between representations, use the "v" query parameter: ...?v=ref or ...?v=full. Using ...?v=default is invalid. Simply leave that parameter off.

Web service calls that return lists of objects will put those objects into the "ref" representation.

Ref

When an object is a child resource on another object (e.g. conceptDatatype property on Concept object) the full ConceptDatatype object is not returned by default.  Instead a "ref" kind of class with String properties for uuid, links, and a display fills the concept.conceptDatatype property.  The ref looks like this:

Ref example
concept.conceptDatatype \->
{
display: "Numeric",
uuid: "8d4a4488-c2cc-11de-8d13-0010c6dffd0f",
links: {
  self: "http:/../openmrs/ws/rest/conceptdatatype/8d4a4488-c2cc-11de-8d13-0010c6dffd0f"
  }
}

To fetch the full ConceptDatatype data, a second call to the links.self uri: http:/../openmrs/ws/rest/conceptdatatype/8d4a4488-c2cc-11de-8d13-0010c6dffd0f is needed.

Default

This representation is returned for objects when there is no "v=" parameter given. Most properties will be included and "refs" of some subobjects will also be listed.

Full

The full representation is meant when to be used when subsequent calls are not desired or you need some uncommonly needed properties (like audit info).

Authentication

Nearly every method in the OpenMRS API requires authentication, therefore, some every method in the webservices module needs to have an authenticated user in order to work.

There is a filter defined on the module that intercepts all calls and authenticates the given request. 

Currently only BASIC authentication is supported.  Header arguments values of ___ and ___ are expected. 

Alternatively, a session token can be used.  GET /openmrs/ws/rest/session with the BASIC credentials will return the current token value.  This token should be passed with all subsequent calls as a cookie named jsessionid=token.

REST API

The pages listed below contain specific web services and object representations.  For general REST web service information, see the module page or the REST user guide

  • No labels