openmrs-esm-api is an in-browser javascript module that exports functions that interact with the OpenMRS API.
import { openmrsFetch, openmrsObservableFetch, getCurrentUser, fhir } from '@openmrs/esm-api';
openmrsFetch('/ws/rest/v1/session').then(response => {
console.log(response.data.authenticated)
}
Instructions for local development
The following functions are exported from the @openmrs/esm-api module:
The openmrsFetch function is a wrapper around the browser's built-in fetch function, with extra handling for OpenMRS-specific API behaviors, such as request headers, authentication, authorization, and the API urls.
- url (required): A string url to make the request to. Note that the openmrs base url (by default "/openmrs") will be automatically prepended to the URL, so there is no need to include it.
- init (optional): A fetch init object. Note that the
body
property does not need to be JSON.stringify()'ed because openmrsFetch will do that for you.
A Promise that resolves with a Response object. Note that the openmrs version of the Response object has already downloaded the HTTP response body as json, and has an additional data
property with the HTTP response json as a javascript object.
import { openmrsFetch } from '@openmrs/esm-api'
const abortController = new AbortController();
openmrsFetch('/ws/rest/v1/session', {signal: abortController.signal})
.then(response => {
console.log(response.data.authenticated)
})
.catch(err => {
console.error(err.status);
})
abortController.abort();
openmrsFetch('/ws/rest/v1/session', {
method: 'POST',
body: {
username: 'hi',
password: 'there',
}
})
To cancel a network request, use an AbortController. It is best practice to cancel your network requests when the user navigates away from a page while the request is pending request, to free up memory and network resources and to prevent race conditions.
The openmrsObservableFetch function is a wrapper around openmrsFetch that returns an Observable instead of a promise. It exists in case using an Observable is preferred or more convenient than a promise.
The arguments to openmrsObservableFetch are exactly the same as the arguments to openmrsFetch.
An Observable that produces exactly one Response object. The response object is exactly the same as for openmrsFetch.
import { openmrsObservableFetch } from '@openmrs/esm-api'
const subscription = openmrsObservableFetch('/ws/rest/v1/session').subscribe(
response => console.log(response.data),
err => {throw err},
() => console.log('finished')
)
subscription.unsubscribe()
To cancel the network request, simply call subscription.unsubscribe();
The fhir
object is an instance of fhir.js that can be used to call FHIR-compliant OpenMRS APIs. See the docs for fhir.js for more info and example usage.
The getCurrentUser function returns an observable that produces zero or more values, over time. It will produce zero values by default if the user is not logged in. And it will provide a first value when the logged in user is fetched from the server. Subsequent values will be produced whenever the user object is updated.
- options (optional): An object with includeAuthStatus boolean property that defaults to false. When includeAuthStatus is set to true, the entire response object from the API will be provided. When includeAuthStatus is set to false, only the user property of the response object will be provided.
An Observable that produces zero or more values (as described above). The values produced will be a user object (if includeAuthStatus is set to false) or an object with a session and authenticated property (if includeAuthStatus is set to true).
import { getCurrentUser } from '@openmrs/esm-api'
const subscription = getCurrentUser().subscribe(
user => console.log(user)
)
subscription.unsubscribe()
getCurrentUser({includeAuthStatus: true}).subscribe(
data => console.log(data.authenticated)
)
Otherwise your code will continue getting updates to the user object even after the UI component is gone from the screen. This is a memory leak and source of bugs.
The refetchCurrentUser function causes a network request to redownload the user. All subscribers to the current user will be notified of the new users once the new version of the user object is downloaded.
None
An observable exactly the same as if you had called getCurrentUser()
.
import { refetchCurrentUser } from '@openmrs/esm-api'
refetchCurrentUser()