How To Download Files via the XNAT REST API

Contents

For the purposes of this instruction we will assume a stored session with the following structure.

CODE

Project:TEST
  Subject:1
    Experiment:MR1
       Scan:1 (TYPE:T1)
          resource:DICOM
             file:1.dcm
             file:2.dcm
          resource:SNAPSHOTS
             file:snap.jpg
       Scan:2 (TYPE:T1)
          resource:DICOM
             file:1.dcm
             file:2.dcm
          resource:SNAPSHOTS
             file:snap.jpg
       Scan:3 (TYPE:T2)
          resource:DICOM
             file:1.dcm
             file:2.dcm
          resource:SNAPSHOTS
             file:snap.jpg
       Scan:4 (TYPE:T2)
          resource:DICOM
             file:1.dcm
             file:2.dcm
          resource:SNAPSHOTS
             file:snap.jpg
 
       Assessment:ASSESS1
          out resource: TEST
             file:something.img
             file:something.hdr

Within the scan, reconstruction, assessment, and resource levels of the URIs, you can use a few special tools to assist in the downloading of data.

Multiple IDs can be separated by commas.
Types can be substituted for scan IDs and reconstruction IDs.

Download Scan Data

How do I download a single scan's DICOM data?

You can download the files for a single scan using the relevant scan ID.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/1/resources/DICOM/files

This will return a list of the DICOM files for scan 1.

Do I have to download the files one by one?

No. You can use the query string parameter format=zip to return the actual files in a compressed archive instead of returning the list of files.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/1/resources/DICOM/files?format=zip

How can I download all of the files for the scan (DICOM and SNAPSHOTS)?

You can download all of the files for the scan by leaving off the resource description.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/1/files?format=zip

How can I download files for multiple scans?

If you know the relevant scan IDs, you can include multiple scan IDs in the URI separated by a comma.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/1,2/files?format=zip

How can I download all of the scans for the session?

You can also use the ALL keyword at the scan identification level.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/ALL/files?format=zip

How can I download all of the T1 scans for the session?

Instead of specifying one or more scan IDs, you can substitute the scan TYPE in the URI at the scan identification level.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/T1/files?format=zip

You can also provide a comma delimited list of scan types.

CODE

/data/projects/TEST/subjects/1/experiments/MR1/scans/T1,T2/files?format=zip

Downloading Image Assessor Data

Similar to scan access, you can use the ALL keyword and comma-separated lists of assessor IDs in your URIs. However, instead of allowing the substitution of the TYPE attribute, you can use the XSI:TYPE of the data you are interested in.

CODE

/data/projects/{PROJECT_ID}/subjects/{SUBJECT_ID}/experiments/{EXPT_ID}/assessors/{ASSESSOR_ID or xsi:type or ALL}/resources/{TYPE or ID}/files