Transitioning to the v1 API

This page explains the key differences between v1beta1 and v1 of the Cloud Healthcare API. It also provides examples of how to transition from v1beta1 to v1.

Beginning August 26, 2020, v1beta1 began updating to a revised version. In this page, the version of v1beta1 before that date is referred to as the "previous v1beta1". The version after that date is referred to as the "new v1beta1".

Complete one of the following paths depending on the version of the v1beta1 API you are using:

Transitioning from previous v1beta1 to v1

This section explains the key differences between the previous v1beta1 and v1 of the Cloud Healthcare API. It also provides examples of how to transition from the previous v1beta1 to v1.

REST paths

All REST paths to the Cloud Healthcare API now use v1 instead of v1beta1. For example:

v1beta1:

GET https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

v1:

GET https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

DICOM changes

Search transactions

In the previous v1beta1, Search transaction methods returned a 200 response code if the search was successful but there were no results that matched the query. The response body also contained an empty array of results.

To align with the DICOM PS3.18 - Web Services standard, Search transaction methods in the new v1beta1 return a 204 response code instead of a 200 response code. Rather than returning an empty array of results, no response body is returned.

DICOMweb delete methods

In the previous v1beta1, the following methods returned an empty response code when successfully executed:

In v1, the methods return a long-running operation. The long-running operation contains done: true when the deletion completes.

Importing DICOM data from Cloud Storage response

In the previous v1beta1, the projects.locations.datasets.dicomStores.import method returned ImportDicomDataErrorDetails in the Operation.error.status.details object. In v1, the method does not return this response for errors. Instead, a URL is populated in Operation.metadata to Cloud Logging, where you can view details about any errors.

FHIR changes

FHIR store creation

When you create a FHIR store, you must specify a FHIR version (DSTU2, STU3, or R4) for the store. If you do not specify a version, the Cloud Healthcare API returns an error.

For example:

gcloud

The following sample shows how to create a FHIR store.

gcloud beta healthcare fhir-stores create FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --version={DSTU2|STU3|R4}

API

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'version': 'FHIR_STORE_VERSION'
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID"

PowerShell

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
      'version': 'FHIR_STORE_VERSION'
  }" `
  
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID" | Select-Object -Expand Content

Schemas when exporting to BigQuery

In the previous v1beta1, you could specify the following schema types in the projects.locations.datasets.fhirStores.export method when exporting FHIR resources to BigQuery:

  • SCHEMA_TYPE_UNSPECIFIED: No schema type specified. Same as LOSSLESS.
  • LOSSLESS A data-driven schema generated from the fields present in the FHIR data being exported, with no additional simplification.
  • ANALYTICS: Analytics schema defined by the FHIR community. See https://github.com/FHIR/sql-on-fhir/blob/master/sql-on-fhir.md.

In v1, the SCHEMA_TYPE_UNSPECIFIED and LOSSLESS schema types are no longer available. There is no longer a default schema type value; if you do not specify the ANALYTICS schema type, the Cloud Healthcare API returns an error.

FHIR conditional methods

FHIR conditional methods are available in the previous and new versions of v1beta1 but are not available in v1. The FHIR conditional methods are:

executeBundle capabilities

Because FHIR conditional methods are unavailable in v1, you cannot call FHIR conditional methods in a bundle when calling projects.locations.datasets.fhirStores.fhir.executeBundle. To use FHIR conditional methods when executing a bundle, use the new v1beta1.

Data de-identification changes

DeidentifyErrorDetails removal

The DeidentifyErrorDetails response is no longer available in v1. Instead, you can view details about any errors in Cloud Logging.

SuccessResourceCount removal

In the previous v1beta1, the following responses contained a SuccessResourceCount field:

In v1, these responses no longer contain a SuccessResourceCount field. Instead, you can view the resources that the Cloud Healthcare API successfully de-identified in the progress_counter.success field of the long-running operation response.

SuccessStoreCount and FailureStoreCount removal

In the previous v1beta1, the following responses contained a SuccessStoreCount field:

DeidentifyErrorDetails also contained a FailureStoreCount field.

In v1, these responses no longer contain a SuccessStoreCount field or a FailureStoreCount field.

FailureResourceCount removal

In the previous v1beta1, the following responses contained a FailureResourceCount field:

In v1, these responses no longer contain a FailureResourceCount field. Instead, you can view the resources that the Cloud Healthcare API failed to de-identify in the progress_counter.failure field of the long-running operation response.

Transitioning from new v1beta1 to v1

This section explains how to transition from the new v1beta1 to v1. It also provides examples of how to transition from new v1beta1 to v1. If you have already completed the v1beta1 updates, you have already completed most of the transition work, but read through the following sections to view all of the changes from new v1beta1 to v1:

REST paths

All REST paths to the Cloud Healthcare API now use v1 instead of v1beta1. For example:

v1beta1:

GET https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

v1:

GET https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

FHIR changes

Schemas when exporting to BigQuery

In the new v1beta1, you can specify the following schema types in the projects.locations.datasets.fhirStores.export method when exporting FHIR resources to BigQuery:

  • SCHEMA_TYPE_UNSPECIFIED: No schema type specified. Same as LOSSLESS.
  • LOSSLESS A data-driven schema generated from the fields present in the FHIR data being exported, with no additional simplification.
  • ANALYTICS: Analytics schema defined by the FHIR community. See https://github.com/FHIR/sql-on-fhir/blob/master/sql-on-fhir.md.

In v1, the LOSSLESS and SCHEMA_TYPE_UNSPECIFIED schema types are no longer available. If you specify either of these schema types, or leave the schemaType field unset, the Cloud Healthcare API returns an error.

FHIR conditional methods

FHIR conditional methods are available in the previous and new v1beta1 but are not available in v1. The FHIR conditional methods are:

executeBundle capabilities

Because FHIR conditional methods are unavailable in v1, you cannot call FHIR conditional methods in a bundle when calling projects.locations.datasets.fhirStores.fhir.executeBundle. To use FHIR conditional methods when executing a bundle, use the new v1beta1.