Updates to the v1beta1 API

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". The scheduled completion date for when the previous v1beta1 behavior will no longer be accepted is September 22, 2020.

This page explains the updates made to v1beta1, which primarily concern the deprecation and addition of fields in requests and responses to and from the Cloud Healthcare API. The implementation of these changes ensures that common methods, resources, responses, requests, and so forth, between v1beta1 and v1 align. This section also provides examples of how to transition from the previous v1beta1 to the new v1beta1.

Annotations changes

Importing and exporting annotations

In the previous v1beta1, annotationStores.import and annotationStores.export used the annotationStore parameter to identify the annotation store. In the new v1beta1, use name instead of annotationStore to identify the annotation store.

Evaluating annotation stores

In the previous v1beta1, annotationStores.evaluate used the evalStore parameter to identify the annotation store used to compare against a golden store. In the new v1beta1, use name instead of evalStore to identify the annotation store used to compare against a golden store.

ImportAnnotationsErrorDetails and ExportAnnotationsErrorDetails

The ImportAnnotationsErrorDetails and ExportAnnotationsErrorDetails responses have been removed in the new v1beta1. Instead, you can view details about any errors in Cloud Logging.

ImportAnnotationsResponse, ExportAnnotationsResponse, and EvaluateAnnotationStoreResponse

  • ImportAnnotationsResponse and ExportAnnotationsResponse, which are contained in the Operation.response field of the import or export's long-running operation, no longer include the annotationStore field or the successCount field. Instead, you can view success and failure counts in the Operation.metadata field returned in the returned long-running operation.
  • EvaluateAnnotationStoreResponse, which is contained in the Operation.response field of the evaluation's long-running operation, no longer includes the evalStore, goldenStore, goldenCount, or matchedCount fields. Instead, to find the matchedCount value, view the success field in Operation.metadata. To find the goldenCount value, add the value of the success field and the value of the failure field in Operation.metadata.

Data de-identification changes

DeidentifyErrorDetails removal

The DeidentifyErrorDetails response is no longer available in the new v1beta1. 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 the new v1beta1, 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 the new v1beta1, 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 the new v1beta1, 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.

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 the new v1beta1, 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 the new v1beta1, 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/v1beta1/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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID" | Select-Object -Expand Content

ImportResourcesResponse, ExportResourcesResponse, ImportResourcesErrorDetails, and ExportResourcesErrorDetails

In the previous v1beta1, projects.locations.datasets.fhirStores.import and projects.locations.datasets.fhirStores.export returned a long-running operation containing ImportResourcesResponse and ExportResourcesResponse, respectively, in the Operation.response field. If any errors occurred, ImportResourcesErrorDetails or ExportResourcesErrorDetails was returned in the Operation.error field.

In the new v1beta1, these responses are returned as success and failure counts in the Operation.metadata field.

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 the new v1beta1, the SCHEMA_TYPE_UNSPECIFIED schema type is no longer available. If you specify SCHEMA_TYPE_UNSPECIFIED or leave the schemaType field unset, the Cloud Healthcare API returns an error.

Locations changes

The projects.locations.get and projects.locations.list methods now require the following permissions:

  • locations.get: healthcare.locations.get on the requested location.
  • locations.list: healthcare.locations.list on the parent Google Cloud project.