Retrieving and Posting Data

Frontend modules interact with the OpenMRS server via the APIs exposed by its modules. In general, most of the endpoints we use are provided by the FHIR Module . Most of the rest are provided by the REST Module , which is documented here .

Endpoints from the FHIR Module should always be preferred, when they are available. FHIR is an interoperability standard which OpenMRS supports.

Some data is available using higher-level functions or custom React hooks provided by @openmrs/esm-framework. Use those public framework exports when available. Internally, these APIs come from packages such as @openmrs/esm-api, @openmrs/esm-emr-api, and @openmrs/esm-react-utils, but application code should import them from @openmrs/esm-framework. See the Framework API reference.

FHIR

To use the FHIR API in React components, prefer useOpenmrsSWR from @openmrs/esm-framework. It wraps SWR , calls openmrsFetch, and attaches an abort controller so the request can be cancelled if the component unmounts.

Here’s an example of using useOpenmrsSWR to retrieve a patient from the FHIR API.

import { fhirBaseUrl, useOpenmrsSWR } from "@openmrs/esm-framework";
 
const { data, error, isLoading, mutate } = useOpenmrsSWR<fhir.Patient>(`${fhirBaseUrl}/Patient/${patientUuid}`);
 
const patient = data?.data;

If you have questions about FHIR support in OpenMRS, you can ask in the FHIR Squad Slack channel .

Other OpenMRS server APIs

Some administrative endpoints will likely never have a proper representation in FHIR (e.g., endpoints for managing encounter types). When no suitable FHIR endpoint is available, you will want to use a different OpenMRS server API. The REST Web Services API  is used widely across many of our frontend modules.

Here’s an example of a custom SWR hook that retrieves visits data.

import { restBaseUrl, type Visit, useOpenmrsSWR } from "@openmrs/esm-framework";
 
interface VisitData {
  results: Array<Visit>;
}
 
/* Custom data fetching hook */
export function useVisits() {
  const url = `${restBaseUrl}/visit?includeInactive=false`;
 
  const { data, error, isLoading, mutate } = useOpenmrsSWR<VisitData>(url);
 
  return {
    visits: data?.data.results ?? [],
    isLoading,
    error,
    mutate,
  };
}

We can leverage this useVisits hook in our visits component as follows:

function Visits() {
  const { visits, error, isLoading } = useVisits();
 
  if (isLoading) {
    return <DataTableSkeleton role="progressbar" />;
  }
  if (error) {
    // render error state;
  }
  if (visits.length) {
    // render visits;
  }
  return (
    // render empty state;
  );
}
 
export default Visits;

The mutate function returned by useOpenmrsSWR can be used to update the cache and trigger a re-render of the component. This is useful when we want to update the UI after a successful mutation.

try {
  await saveVisitNote(payload);
  await mutate();
  closeWorkspace({ discardUnsavedChanges: true });
 
  // show success toast
} catch (error) {
  // handle error
}

Posting data to the server

Here’s an example that demonstrates posting session data to the server.

import { openmrsFetch, sessionEndpoint } from "@openmrs/esm-framework";
 
const abortController = new AbortController();
 
const response = await openmrsFetch(sessionEndpoint, {
  method: "POST",
  body: {
    username,
    password,
  },
  signal: abortController.signal,
});
 
const session = response.data;

openmrsFetch automatically prefixes relative paths with window.openmrsBase, requests JSON responses by default, stringifies plain-object request bodies before sending them, and resolves to a FetchResponse<T> whose parsed response body is available as response.data. For FHIR URLs under fhirBaseUrl, it also adds _summary=data unless the URL already includes a _summary parameter.

It is best practice for POST requests to have an AbortController . You should ensure that AbortController.abort() is called when the component is unmounted if the request is not yet completed.

In a React Component this is usually accomplished by making the request in a useEffect hook:

useEffect(() => {
  const abortController = new AbortController();
  someFetchFunction(abortController).then(setResult).catch(setError);
  return () => abortController.abort();
}, []);

API Objects

Some API objects are made available via React hooks (or via framework-agnostic subscriptions). Import the hooks and the subscription-yielding equivalents from @openmrs/esm-framework. See for example useVisitTypes and the corresponding getVisitTypes.