RESTful API

RESTful API

The C-CDA Receiver exposes JSON resources with a simple RESTful API, with URLs that match the following template:

/patients/:pid/:hierarchyLevel/:dataType/:resourceId

• :pid Patient identifier
• :hierarchyLevel C-CDA structure (one of: documents, sections, organizers, entries)
• :dataType C-CDA data type to query for (e.g. medications, problems, vitals -- see below)
• :resourceId Unique identifier for this resource. (You can omit this parameter to query for all resources of a given type.)

Each C-CDA is broken down into a set of resources that are individually stored and exposed. A key aspect of how the C-CDA Receiver exposes data is that individual structured elements are available at multiple levels of granularity:

• documents expose an entire C-CDA in a single JSON structure
• sections expose C-CDA sections (e.g. Medications, Problems) as JSON
• organizers expose C-CDA organizers (e.g. Lab Panel, Problem Concern) as JSON
• entries expose individual C-CDA entries (e.g. Medication, Lab Result) as JSON

You can find the same data at all four levels, and you'll want to tailor your app to request exactly what it needs. For example,if your app is interested in a list of all historical HbA1c values, it might query for /patients/:pid/entries/results. If your app is interested in entire medication lists, it might query for /patients/:pid/sections/medications. Or to displaying whole documents, it might query /patients/:pid/documents/ccda.

Navigating between resources with links

The C-CDA Receiver allows you to query data at any of the four levels of the hierarchy, but also allows you to discover where an individual resource fits: you can append /links to any resource URI to retrieve its absolute path in the hierarchy.

Getting the raw data

The C-CDA Receiver exposes raw C-CDA XML for those times when simplified JSON resources aren't powerful enough. To fetch the raw XML content for a document, just

GET /patients/:pid/documents/ccda/:documentId/raw

Available Resources

Demographics

Section-level Demographics

GET /patients/:pid/sections/demographics

List of all demographics sections for patient :pid. In general, one demographics section will be available from each C-CDA document about the patient.

Most recent Demographics

GET /patients/:pid

Convenient shortcut to the most recent demographics available for patient :pid

Vital Signs

Section-level Vitals

GET /patients/:pid/sections/vitals

List of all vital signs sections for patient :pid. A vital signs section contains organizers which contain individual observations.

Organizer-level Vitals

GET /patients/:pid/organizers/vitals

List of all vital signs organizers for patient :pid. Organizers represent sets of vital signs measured at the same time. For example, systolic and diastolic blood pressures measured together belong to the same organizer.

Entry-level Vitals

GET /patients/:pid/entries/vitals

List of all vital sign entries for patient :pid. Entries represent individual vital sign observations such as a systolic blood pressure, weight, or BMI.

Lab Results

Section-level Results

GET /patients/:pid/sections/results

List of all results sections for patient :pid. A results section contains organizers (lab panels) which contain individual observations.

Organizer-level Results

GET /patients/:pid/organizers/results

List of all organizers for patient :pid. Organizers (lab panels) represent sets of results measured together. For example, a complete blood count that includes Hemoglobin, WBC, and Platelets.

Entry-level Results

GET /patients/:pid/entries/results

List of all result entries for patient :pid. Entries represent individual result observations such as a single HbA1c, WBC, or Cholesterol measurement.

Medications

Section-level Medications

GET /patients/:pid/sections/medications

List of all medications sections for patient :pid. A medications section contains medications that were prescribed or reported for a patient.

Entry-level Medications

GET /patients/:pid/entries/medicationsPrescribed

List of all medications prescribed for a patient.

GET /patients/:pid/entries/medicationsReported

List of all medications reported for a patient.

Immunizations

Section-level Immunizations

GET /patients/:pid/sections/immunizations

List of all immunizations sections for patient :pid. An immunizations section contains immunizations that were given, planned, or skipped.

Entry-level Immunizations

GET /patients/:pid/entries/immunizationsGiven

List of all immunizations administered to a patient.

GET /patients/:pid/entries/immunizationsPlanned

List of all immunizations planned for a patient.

GET /patients/:pid/entries/immunizationsSkipped

List of all immunizations explicitly skipped (including a reason for skipping, when available).

Social History

Social History Section

GET /patients/:pid/sections/socialHistory

List of all social history sections for patient :pid. A social history section includes smoking observations.

Entry-level Smoking Status Obsercations

GET /patients/:pid/entries/smokingStatus

List of all smoking status observations available for a patient.