HTTP API for DicomServer

In addition to acting as a DICOM C-STORE SCP (i.e., a receiver for storage operations), DicomServer has an HTTP interface for upload session management. This HTTP API was developed for the upload applet to correct a deficiency of the DICOM standard: the lack of any mechanism to describe how many files are contained in a study, or to indicate that a study has been completely transferred and is ready for further processing.

Uploading a session using both DICOM C-STORE and DicomServer HTTP follows these steps:

  1. Client (e.g., the upload applet) sends a session manifest, describing the DICOM study to be sent.
  2. Server responds with a list of SCP parameters for the C-STORE operation, and a URL for HTTP management of the session.
  3. Client uses C-STORE to push the DICOM data.
  4. When upload is complete, client issues an HTTP PUT to the session management URL.
  5. Server responds with the new location of the session, in either the project prearchive or the archive.

Normal operation

A detailed description of each step of a successful operation follows. We use http://DicomServer:port/ to indicate the base URL of the DicomServer HTTP interface.

1. Client sends a session manifest

The client makes an HTTP POST request to http://DicomServer:port/session . The message body (entity) is a JSON object describing the session to be sent:

"project": project name,
"subject": subject ID,
"subject_label": subject label,
"session_label": session label,
"uid": Study Instance UID,
[XNAT variables ...]
"scans": [scan manifests ...]

The XNAT variables are fields to be set in the XNAT session document. The form for these XNAT variables is:

"xnat:path/to/field": value

Here is an example of an XNAT variable used by the upload applet:

"xnat:petSessionData/tracer/name": "PIB"

The scan manifests describe the individual DICOM series that make up the study. Each element in the scan manifests array is a JSON object:

"uid": Series Instance UID,
"modality": series modality,
"count": number of files in series

2. Server replies with session metadata

The server response to the POST operation has status code 201 (Created), the HTTP header Location contains a URL for management of the new upload session, and the response body is a summary of C-STORE SCP parameters:

"scp_host": SCP hostname,
"scp_ae_title": SCP AE title,
"scp_port": SCP IP port,
"tls": TLS cipher name (empty string "" if TLS not used)

Once this response has been received, the client may start sending data.

3. Client sends data via DICOM C-STORE

The client acts as a DICOM C-STORE SCU to send data to DicomServer, the SCP. The SCU AE title may be set to any value and is used by DicomServer only for display in some log messages.

4. Client commits session

When the client is finished sending data, it commits the session by issuing an HTTP PUT to the session URL that was originally provided by the server in the Location header in step 2. The content of the request – the headers and body – are ignored by DicomServer.

5. Server sends location of data in archive or prearchive

The server replies with a description of the new location for the uploaded session. If the session was placed in the prearchive, the response entity looks like:

"in_prearchive": project name

if the session was immediately archived, the response entity contains the URL for the archived session:

"url": archived session URL

Forthcoming changes in DicomServer HTTP API

This document describes the DicomServer HTTP API for DicomServer versions 1.4 through 1.4.2b2 and UploadAssistantApplet version 0.1.x . Some changes have been made for the not-yet-released versions 1.4.2b3+ and 0.2.x. In particular, the upload applet will be using MIRC-style HTTP POST operations instead of DICOM C-STORE to upload data files, and clients are encouraged to use a URL within the XNAT webapp instead of directly accessing DicomServer.