DICOM conformance statement

DICOM stores within the Cloud Healthcare API support a subset of the RESTful web services specified in the DICOM PS3.18 - Web Services standard (commonly referred to as DICOMweb). Specifically, they support the Studies Service and Resources (previously referred to as the WADO-RS, STOW-RS, and QIDO-RS services).

Additionally, the Cloud Healthcare API supports a proprietary web service for deleting DICOM instances.

The Cloud Healthcare API does not support the URI Service, the Worklist Service, the Non-Patient Instance Service or any of the Capabilities Transactions.

Retrieve transaction

The Retrieve Transaction is a RESTful web service for retrieving DICOM imaging data.

The Retrieve Transaction supports the retrieving following resources:

  • DICOM Resources:
    • Study
    • Series
    • Instance
    • Frames
    • Bulkdata
  • Metadata Resources
    • Study
    • Series
    • Instance
  • Rendered Resources
    • Instance
    • Frames

It does not support Thumbnail resources.

DICOM study/series/instances

The following Accept Headers are supported:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (default)
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

DICOM instances

In addition to the above Accept Headers, RetrieveInstance supports single part content types for convenience:

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

This is not part of the official DICOMweb standard.

DICOM frames

The following Accept Headers are supported:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (default)
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

A transfer syntax of * allows the user to request no transcoding be done, so the transfer syntax of the uploaded file will be used. For application/octet-stream the bulk data will be returned in whatever format it appears in the uploaded DICOM file.

Rendered resources

The following Accept Headers are supported:

  • image/jpeg (default)
  • image/png

Only retrieving of Instance or Frame resources is supported.

No URL parameters are supported.

Metadata resources

The following Accept Headers are supported:

  • application/dicom+json (default)
  • multipart/related; type=application/dicom+xml

RetrieveMetadata doesn't return any attribute which has a DICOM Value Representation of OB, OD, OF, OL, OW, or UN.

No BulkDataURIs are returned in the metadata.

Bulkdata resources

The following Accept Headers are supported:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

Only retrieval of PixelData is supported.

Supported transfer syntaxes

The above Accept headers describe what media types & transfer syntaxes you can request from the API, but this may not always be possible depending on the transfer syntax of the original file that was uploaded. In particular, transcoding is only possible from the following transfer syntaxes:

  • 1.2.840.10008.1.2 (Little Endian Implicit)
  • 1.2.840.10008.1.2.1 (Little Endian Explicit)
  • 1.2.840.10008.1.2.2 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.4.50 (JPEG Baseline Process 1)
  • 1.2.840.10008.1.2.4.57 (JPEG Lossless)
  • 1.2.840.10008.1.2.4.70 (JPEG Lossless Selection Value 1)
  • 1.2.840.10008.1.2.4.90 (JPEG 2000 Lossless Only)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE Lossless)

If the original file has a transfer syntax other than that in the above list and you request transcoding to another format, an error will be returned.

In order to disable transcoding and retrieve any file from the API you can set transfer-syntax=* in your Accept header.

Status codes

Code Meaning
200 (OK) The response payload contains representations for all of the Target Resource(s).
400 (Bad Request) The request was invalid (e.g. bad query parameters or headers) for the specified Target Resource(s) (e.g. missing pixel data).
401 (Unauthorized) The request is missing authentication credentials.
403 (Permission Denied) The authenitcated user doesn't have access to this resource (or the resource doesn't exist).
406 (Not Acceptable) The server doesn't support any of the Acceptable Media Types.
429 (Too Many Requests) The client is exceeding its quota.
503 (Service Unavailable) The server is currently unavailable or the request exceeded its deadline.

Store transaction

The Store Transaction is a RESTful web service for storing DICOM imaging data.

The store transaction either accepts Part 10 DICOM binary files directly or it accepts splitting of a DICOM file into metadata (represented in JSON) and bulk data. These 2 versions have different semantics that are described in the following sections.

DICOM part 10 binary files

The following Content-Types are supported:

  • multipart/related; type=application/dicom
  • application/dicom

No coercing or replacing of attributes is done by the server.

This version accepts all transfer-syntaxes and SOP classes. Only minimal validation of the DICOM file is done to extract some key metadata attributes.

Note that for convenience, the Store Transaction also accepts a single part HTTP request with a single DICOM instance with content type application/dicom. This is not part of the official DICOMweb standard.

See Storing a DICOM instance for the associated how-to guide.

JSON metadata and bulk data requests

When storing instances using JSON metadata and bulk data, the first multipart part must consist of a JSON array of DICOM instances.

The first part must have a Content-Type of application/dicom+json; transfer-syntax=TransferSyntaxUID where TransferSyntaxUID is the transfer syntax which was used to encode binary data in InlineBinary objects. If no InlineBinary objects are present in the metadata, the transfer-syntax parameter can be omitted.

The following DICOM elements are required to be present in every instance in the JSON metadata:

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

The SpecificCharacterSet element must be set to ISO_IR 192, and the JSON metadata must be encoded in unicode UTF-8. The TransferSyntaxUID can be set to any valid transfer syntax, except for the following unsupported transfer syntaxes:

  • 1.2.840.10008.1.2.2 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

Within the JSON metadata, the user can specify multiple BulkDataURIs for DICOM tags with VRs of OB, OW, or UN. These BulkDataURIs indicate that the binary data for the tag which contains the URI will be sent in a following part which has the Content-Location header set to the BulkDataURI.

Each instance in the JSON metadata can have at most one BulkDataURI. There must not be any duplicate BulkDataURIs in the JSON metadata. Compressed image bulk data must only be sent for the PixelData tag, and when sent, the transfer syntax specified in the bulk data part must match the value of the instance's TransferSyntaxUID element.

The following Content-Types are supported for bulk data parts:

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

An alternative method to specify binary data is to encode it as an InlineBinary base64 encoded string. This is supported for all tags except PixelData, which must be sent as a bulk data part. When InlineBinary objects are used in the JSON metadata, the transfer syntax which was used for encoding must be specified in the Content-Type of the JSON metadata part.

The server doesn't derive image pixel description macro attributes.

See Creating DICOM instances from JSON metadata and JPEG images for the associated how-to guide.

Response

On an error, either an additional FailureDetail (0009, 0097) tag (for XML responses) or FailureDetailJSON (0009,1097) tag (for JSON responses) will be returned. The FailureDetail tag provides a human-readable description of the error.

If an identical DICOM instance already exists in the DICOM store, a WarningReason (0008, 1196) tag is returned containing the 45070 status code. This is followed by either a WarningDetail (0009, 0096) tag (for XML responses) or a WarningDetailJSON (0009, 1096) tag (for JSON responses). The WarningDetail provides a human-readable description of the warning. If a DICOM instance is not identical to an existing one but has the same <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> tuple as one in the DICOM store, then a Processing failure error will be returned with an "already exists" FailureDetail tag.

The response can be in either JSON or XML format which can be controlled via the following Accept header values:

  • application/dicom+xml (default)
  • application/dicom+json

Status codes

Code Meaning
200 (OK) The resource was successfully stored.
400 (Bad Request) The request was invalid (e.g. unsupported media type or transfer syntax).
401 (Unauthorized) The request is missing authentication credentials.
403 (Permission Denied) The authenitcated user doesn't have access to this resource (or the resource doesn't exist).
406 (Not Acceptable) The server doesn't support any of the Acceptable Media Types.
409 (Conflict) At least one resource wasn't successfully stored (e.g. invalid DICOM file). Check the FailureDetail tag in the response body for more information.
429 (Too Many Requests) The client is exceeding its quota.
503 (Service Unavailable) The server is currently unavailable or the request exceeded its deadline.

Search transaction

The Search Transaction is a RESTful web service for querying DICOM imaging metadata.

The Cloud Healthcare API supports searching for studies, series and instances.

Search parameters

Searching by the following tags is supported:

  • Studies:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Series: all study level search terms and
    • SeriesInstanceUID
    • Modality
  • Instances: all study/series level search terms and
    • SOPInstanceUID

Only single value, exact matching is supported, except for StudyDate which supports range queries and PatientName which supports fuzzy matching.

The following additional URL parameters are supported:

  • fuzzymatching: If set to true, fuzzy matching will be applied to the PatientName tag. Fuzzy matching will perform tokenization and normalization of both the value of PatientName in the query and the stored value. It will match if any search token is a prefix of any stored token. For example, if PatientName is "John^Doe", then "jo", "Do" and "John Doe" will all match. However "ohn" will not match.

Paging is supported using the limit and offset query parameters. There is no Warning response header if no more results are available. You must execute an extra query to determine if there are more results.

  • limit: Maximum number of results that should be returned, up to a maximum of 5,000 for studies/series and 50,000 for instances. The default number of results is 100 for studies/series and 1,000 for instances.

  • offset: Number of results to skip in the beginning.

Timezone Offset From UTC is not supported.

Returned results

The response can be in either JSON or XML format which can be controlled via the following Accept header values:

  • application/dicom+json (default)
  • multipart/related; type=application/dicom+xml

By default the following attributes will be returned:

  • Studies:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Series:
    • SpecificCharacterSet
    • Modality
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instances:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Rows
    • Columns
    • BitsAllocated
    • NumberOfFrames

For includefield=all, the default attributes will be returned along with the following attributes:

  • Studies:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Series:
    • SeriesNumber
    • Laterality
    • SeriesDate
    • SeriesTime
  • Instances: all attributes present in the DICOM instance except for any attribute which has a DICOM Value Representation of OB, OD, OF, OL, OW, or UN.

No BulkDataURIs are returned in the metadata.

Inconsistent/invalid metadata

In the case of SearchForStudies/SearchForSeries there is a potential for inconsistent study/series level metadata across multiple instances. For example, two instances could be uploaded with the same StudyInstanceUID but have different StudyDates. In this case, the search behavior is not well defined. Searching by that value may work in some cases, but not others and the returned value may vary across different calls.

Status codes

Code Meaning
200 (OK) The response payload contains representations for all of the Target Resource(s).
400 (Bad Request) The request was invalid (e.g. invalid query parameters).
401 (Unauthorized) The request is missing authentication credentials.
403 (Permission Denied) The authenitcated user doesn't have access to this resource (or the resource doesn't exist).
406 (Not Acceptable) The server doesn't support any of the Acceptable Media Types.
429 (Too Many Requests) The client is exceeding its quota.
503 (Service Unavailable) The server is currently unavailable or the request exceeded its deadline.

Deletion

The Cloud Healthcare API supports the following proprietary action types:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

These use the same request paths as their WADO-RS counterparts (RetrieveStudy, RetrieveSeries, and RetrieveInstance, respectively). Instead of an HTTP GET request, a DELETE request is used. The effect is that the specified study, series, or instance is deleted along with all the DICOM resources contained in it.

Status codes

Code Meaning
200 (OK) The request resource was deleted.
400 (Bad Request) The request was invalid.
401 (Unauthorized) The request is missing authentication credentials.
403 (Permission Denied) The authenitcated user doesn't have access to this resource (or the resource doesn't exist).
429 (Too Many Requests) The client is exceeding its quota.
503 (Service Unavailable) The server is currently unavailable or the request exceeded its deadline.

Accept headers

Some of the above methods provide the ability to control the response format using HTTP Accept headers. Wildcard matching is supported at both the top level (e.g. */*) and subtype (e.g. image/*). Specifying a q value is also supported to indicate relative preference. If a q value is not specified for an Accept header, it is set to the default value of 1.0.

In the event that multiple Accept headers are specified and there is a tie between the highest preference Accept headers, the server will choose the Accept header. Clients should not depend on the server's choice of Accept header in this scenario.

Supported SOP classes

The Cloud Healthcare API can ingest and do basic retrieval of all DICOM SOP classes. For any retrieval that requires transcoding between image formats, see supported transfer syntaxes for a list of supported transfer syntaxes.

Var denne siden nyttig? Si fra hva du synes:

Send tilbakemelding om ...

Cloud Healthcare API