- About XNAT
- News & Events
- XNAT Marketplace
- Contact Us
The REST API is currently accessible on XNAT Central, http://central.xnat.org. It is advised that you become familiar with the XNAT web application before attempting to use the REST API.
All restful services require a valid user account. This can either be specified via the HTTP Authorization property (using Basic Authorization) or can be performed in an existing Server session (using the JSESSION_ID cookie). As a shortcut, you can use the XNATRestClient to execute REST interactions from a command prompt: xnat_tools.zip (from XNAT 1.4)
A quick is tutorial available at the bottom.
When querying a resource (GET) which returns a list of items (projects, subjects, experiments, etc), you can use a query string variable 'format=html' to specify the return type of the result. If you are using a REST compliant client, you can also do this using the 'Accept' HTTP header. However, the 'format' tag can override the Accept header, and is especially useful in browsers.
There are currently 4 supported list types: html, json, xml or csv. Specifying any of these values with the format tag, will return a result of that type.
EXAMPLE, log into http://central.xnat.org/.
Enter the url: http://central.xnat.org/data/archive/projects?format=html. Now, try the http://central.xnat.org/data/archive/projects?format=xml.
When querying indvidual resources, the xnat xml document will be returned (except when referencing uploaded files).
Creating projects, subjects, experiments, scans, reconstructions and assessments is simple using the REST API. Simply perform a POST or PUT to the relevant API, and your resource will be generated.
You can use several routes to create a resource via the REST API.
Get a list of the subjects in a project:
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects?format=csv"
Create a subject:
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000"
This will create an empty subject within your project.
To customize the demographics of the subject you can either add query string parameters or submit an XNAT xml document.
You can modify your entry via the query string by adding xml path parameters to identify the entries you want to edit. You can identify the xml path by review the xnat.xsd.
To modify the gender and handedness of this subject, I'll append the following paths separated by a &. Keep in mind that the querystring parameters must be seperated from the actual URI by a ?.
xnat:subjectData/demographics@xsi:type=xnat.demographicData/gender = male xnat:subjectData/demographics@xsi:type=xnat.demographicData/handedness = left
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000?xnat:subjectData/demographics@xsi:type=xnat.demographicData/gender=male&xnat:subjectData/demographics@xsi:type=xnat.demographicData/handedness=left"
For your convenience, a few parameters have been added as shortcuts. The abbreviated term can be substituted in the querystring for the full XML PATH. The list of available shortcuts is here.
Instead of specifying each field in the query string, you can build an xml file describing your subject. This can be uploaded with your PUT to set the details of the subject.
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000" - local ./YOURTEST_subject.xml ./YOURTEST_subject.xml
<xnat:Subject ID="" project="JUNIT1" group="control" label="1" src="12" xmlns:xnat="http://nrg.wustl.edu/xnat" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <xnat:demographics xsi:type="xnat:demographicData"> <xnat:dob>1990-09-08</xnat:dob> <xnat:gender>male</xnat:gender> <xnat:handedness>right</xnat:handedness> <xnat:education>12</xnat:education> <xnat:race>12</xnat:race> <xnat:ethnicity>12</xnat:ethnicity> <xnat:weight>12.0</xnat:weight> <xnat:height>12.0</xnat:height> </xnat:demographics> </xnat:Subject>
Similar to create resources, you can modify existing resources using the HTTP PUT method on the relevant URI. You can use either a query string xml path variable to specify your modification, or a full xml file.
Notice that, by default, submitting your PUT command will not delete content which is absent from your submitted message. This allows you to submit 'partial' xml documents. If you want to delete the information which is not contained in the document, add the query parameter 'allowDataDeletion=true'.
Similarly to creating and modifying, you can use delete existing resources using the HTTP DELETE method on the relevant URI.
To delete a subject
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m DELETE -remote "/data/archive/projects/YOURTEST/subjects/1000"
By default, any files which have been uploaded for the entry, will not be deleted from the file system. To force the deletion of these files include the removeFiles attribute as a query string parameter.
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m DELETE -remote "/data/archive/projects/YOURTEST/subjects/1000?removeFiles=true"
Files can be uploaded at any of the following levels:
To upload a file, you will need to specify the pertinent URI above and then add the file name. The file name can include a relative directory structure.
So if I have three files which I want to attach to a scan, I could use the following XNATRestClient commands:
./file1.img = /data/archive/projects/PROJECT_ID/subjects/SUBJECT_ID/experiments/EXPT_ID/scans/SCAN_ID/files/file1.img ./subfolder/file2.img = /data/archive/projects/PROJECT_ID/subjects/SUBJECT_ID/experiments/EXPT_ID/scans/SCAN_ID/files/subfolder/file2.img ./file3.img = /data/archive/projects/PROJECT_ID/subjects/SUBJECT_ID/experiments/EXPT_ID/scans/SCAN_ID/files/file3.img
I could upload these files using the following commands:
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/file1.img" - local ./file1.img XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/subfolder/file2.img" - local ./subfolder/file2.img XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/file3/img" - local ./file3.img
NOTE: If you are using a different utility to upload your files to the REST API, the default expectation of XNAT is that the files will be posted as part of a Multi-Part Form data (similar to a post from within an HTML application). If your tool writes the contents of the file directly into the message body, use the ?inbody=true parameter to force XNAT to parse the contents of the body as the file itself. Using this option requires that you specify what your file should be called in the URI.
To group files together you will need to define a resource, which you can map multiple files to. Instead of uploading a file to a specific resource uri (URI/files) you can define a resource first. A resource can contain one to many files. This especially useful in uploading file formats which contain multiple files (header and image) or collections of files which you want to be bundled together to represent a single resource.
As an example, if you want to upload an analyze reconstruction you would first create a resource for the reconstruction, then upload files to that resource.
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE" XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files" - local ./file1.hdr XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m PUT -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files" - local ./file1.img
These files would then be retrievable:
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files/file1.hdr" XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/reconstructions/1000_mr_1_r1/resources/ANALYZE/files/file1.img"
You can request a list of files for a given resource using the GET method on the above URIs. To get the list of files for the scan images I uploaded previously I could use:
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files"
This would return a list of the three files I previously uploaded.
I could then retrieve each file the URIs specified in the listing OR the URI I used to insert the file originally.
XNATRestClient -host http://central.xnat.org -u USERNAME -p PASSWORD -m GET -remote "/data/archive/projects/YOURTEST/subjects/1000/experiments/1000_mr_1/scans/1/files/file1.img" -local ./downloads/file1.img
Please email us with additional questions: firstname.lastname@example.org.