API structure

This page describes the structure of Cloud Healthcare API paths and operations and how they can be used to access and manage data.


Healthcare data in datasets and data stores can be accessed and managed using a REST API that identifies each data store using:

  • A Google Cloud project
  • A Google Cloud location
  • The dataset ID
  • The data store type
  • The data store ID

The API also implements modality-specific standards for access that are consistent with industry standards for that modality.

Administrative operations

Administrative operations are available for datasets and all data stores. They primarily consist of creating, reading, updating, and deleting (CRUD) datasets and data stores. Administrative operations are consistent with most Google Cloud (Google Cloud) APIs and do not require any adherence to specific modality standards.

Examples of administrative operations include:

  • Creating, deleting, getting, listing, and patching datasets and data stores
  • Setting, getting, and testing IAM permissions

Resource names

A resource name consists of, at minimum, a project ID and a location. It can extend to include a dataset, data store, and any of a data store's child resources.

The format for a resource name for a data store that resides within a Cloud Healthcare API dataset looks like this:


For example, the resource name for an HL7v2 store called clinical-store1 looks like this:


This resource name shows a project called my-project in the us-central1 region. The project contains a dataset called my-dataset, and the dataset contains an HL7v2 store called clinical-store1.

Operations on a location, dataset, data store, or any of a data store's child resources all require that a resource name is provided either in the REST path or the gRPC request.

Modality paths for modality-specific operations

Operations that access data in a modality-specific data store use a request path that consists of two pieces: the resource name (for identifying the data store to access), and a modality path (for identifying the actual data to retrieve).

FHIR resource modality paths

For example, the full request path for reading a specific FHIR Patient resource using the patient's ID might look like the following:


with /Patient/PATIENT_ID being the modality path (structured according to the FHIR standard) for the Patient resource whose identifier is specified by PATIENT_ID.

DICOMweb modality paths

DICOMweb requests to retrieve all studies for a given patient would look like this:


As another example, a request to retrieve all instances in a given study and series would look like this:


A request to retrieve an instance would look like this:


In all of these examples, the modality path specification is consistent with the DICOMweb standard path structure.