icon-toolbox.png
XNAT Tools


Client Tools


XNAT Desktop


XNAT DICOM Gateway


Web Services


Web Services: XNAT Rest API


Web Services: Examples

[Edit Nav] ]



XNAT 1.3 Web Services (SOAP-Based Web Services)


A limited number of Web Services exist for XNAT versions 1.3 & 1.4. Client tools for XNAT 1.4 are available at http://nrg.wustl.edu/1.4/xnat_tools.zip.

In 1.4 the list of current web service tools are:

CreateUserSession

This service will create an HTTP session based on the username and password (which are encapsulated in the SOAP message). The ID of the created HTTP Session is passed back to the user as a return string.
WSDL: http://central.xnat.org/axis/CreateServiceSession.jws?wsdl

CloseUserSession

This service will close an HTTP session based on the passed HTTP Session ID.
WSDL: http://central.xnat.org/axis/CloseServiceSession.jws?wsdl

Search

This service uses two steps to search for XML documents. First it uses a SOAP based GetIdentifiers service which process the search and retrieves the Identifiers for the matching entries. Then, it uses a REST style URI to request XML files for the corresponding entries.
WSDL: http://central.xnat.org/axis/GetIdentifiers.jws?wsdl GetIdentifiers takes in search parameters and outputs matching IDs.

ArcGet

This service uses several steps to retrieve imaging data from the server. It first instantiates an HTTP Session, then queries for a Session summary for the supplied Imaging session id, then retrieves the actual files. The query for the session summary is via a SOAP request,
http://central.xnat.org/axis/VelocitySearch.jws?wsdl. The Request for the imaging files uses a standard HTTP request to the ArcGet screen.

ArcPut

This service allows users to upload a set of files to be attached to an existing session. The files will be considered MISC files, but can be given tags to identify their purpose and role.

StoreXML

This service allows users to upload XML documents to the XNAT server. These documents will be reviewed and stored to the XNAT backend database.

StoreXAR

This service allows users to upload xml files with their corresponding image data. The image files will be moved to the Image Session folder. Any XNAT compliant file references in the corresponding xml documents will be updated with the path of the stored resources.

For more information on StoreXAR, consult the StoreXAR documentation.


XNAT 1.4 Web Services API

The web service API targeted for 1.4 release will include a collection of web services using a REST-like structure. The eventual goal is to replicate all of the functionality of the website within the remote service functionality. The services are grouped into the following categories: HTTP Session Management, Site Administration, Project Management, Search, Upload/Download.

HTTP Session Management

Create User Session
This service will create an HTTP session based on the username and password. The ID of the created HTTP Session is passed back to the user as a return string. This is used when processing multiple requests to a XNAT Server to increase efficiency and performance.

INPUTS:
username : STRING
password : STRING

OUTPUTS:
HTTP Session ID : STRING

Close User Session
This service will close an HTTP session based on the passed HTTP Session ID.

INPUTS:
HTTP Session ID : STRING

OUTPUTS:
Status : STRING

Site Administration

Create User
This service will create a new user account. The user details are specified in an xml document corresponding to the xdat:User xsd type.

INPUTS:
HTTP Session ID : STRING
USER_XML : XML STRING (xdat:User in security.xsd)

OUTPUTS
USER ID : INTEGER


Search

Request Possible Data Types
Returns list of searchable data types. These represent the data types in this XNAT server which this user has permission to review.

INPUTS:
HTTP Session ID : STRING

OUTPUTS:
Results XML

<results TITLE="Data-Types">
 <columns>
   <column>Data-Type</column>
   <column>CODE</column>
   <column>description</column>
 </columns>
 <rows>
   <row>
     <cell>xnat:mrSessionData</cell>
     <cell>MRI</cell>
     <cell>MRI Imaging Session</cell>
   </row>
   <row>
     <cell>xnat:subjectData</cell>
     <cell>Subject</cell>
     <cell>Study Participant</cell>
   </row>
   <row>
     <cell>xnat:ctSessionData</cell>
     <cell>CT Imaging Session</cell>
   </row>
 </rows>
</results>


Request Possible Fields
Given a data type, returns a list of the data types fields including XPATH, data type, description, ID, header.

INPUTS:
HTTP Session ID : STRING
Data-Type : STRING

OUTPUTS:
Results XML

<results TITLE="Possible Fields">
 <columns>
   <column DESC="Brief ID used to refer to this field">FIELD_ID</column>
   <column DESC="Description of this field">DESCRIPTION</column>
   <column DESC="XPATH reference to this field">XPATH</column>
   <column DESC="DEFINED|REFERENCE|DERIVED|CUSTOM">SRC</column>
   <column>Reference Element</column>
   <column>Reference Match</column>
 </columns>
 <rows>
   <row>
     <cell>DATE</cell>
     <cell>Experiment Date</cell>
     <cell>xnat:mrSessiondata/date</cell>
     <cell>DEFINED</cell>
     <cell></cell>
     <cell></cell>
   </row>
   <row>
     <cell>SCAN</cell>
     <cell>MR Scan</cell>
     <cell>xnat:mrSessionData/scans/scan</cell>
     <cell>REFERENCE</cell>
     <cell>xnat:mrScanData</cell>
     <cell>xnat:mrSessionData/ID=xnat:mrScanData/image_session_id</cell>
   </row>
   <row>
     <cell>AGE</cell>
     <cell>Age upon experiment</cell>
     <cell>xnat:mrSessionData/AGE</cell>
     <cell>DERIVED</cell>
   </row>
   <row>
     <cell>OTHER_SCAN_PARAM</cell>
     <cell>Other Scan Parameter</cell>
     <cell>value:OTHER_SCAN_PARAM</cell>
     <cell>CUSTOM</cell>
   </row>
 </rows>
</results>
 

Search
XNAT XML Searches are processed via a Search XML. Results can be returned as XML Listing, XNAT XML, CSV. The paths for the joins and fields can be queried from the 'Request Possible Fields' Service. The join elements are optional. If they are absent, XNAT will attempt to connect the data-types on its own. When quering for XNAT XML, the fields can be left off to retrieve the entire documents.

INPUTS:
HTTP Session ID : STRING
SEARCH_XML : STRING

<searchAPI:search ID="" RETURN_TYPE="xml|listing|csv" paging="true|false" page_size="integer" page_num="integer">
  <root_element_name>xnat:mrSessionData</root_element_name>
  <joined_elements>
     <joined_element ALIAS="SCAN1" element_name="xnat:mrScanData">
       <join rootXPATH="xnat:mrSessionData/ID" foreignXPATH="xnat:mrScanData/image_session_id" comparison="EQUALS">
     </joined_element>
     <joined_element ALIAS="FIELD1" element_name="xnat:experimentData_field">
       <join rootXPATH="xnat:mrSessionData/ID" foreignXPATH="xnat:experimentData_field/image_session_id" comparison="EQUALS">
       <join foreignXPATH="xnat:experimentData_field/name" value="age" comparison="EQUALS">
     </joined_element>
     <joined_element ALIAS="CLIN" element_name="cnda:clinicalAssessmentData">
       <join rootXPATH="xnat:mrSessionData/subject_id" foreignXPATH="cnda:clinicalAssessmentData/subject_id" comparison="EQUALS">
       <join rootXPATH="xnat:mrSessionData/date" foreignXPATH="cnda:clinicalAssessmentData/date" comparison="CLOSEST">
     </joined_element>
     <joined_element ALIAS="CUSTOM1" TYPE="subquery">
       <search>*******</search>
     </joined_element>
  </joined_elements>
  <fields>
    <field XPATH="@ROOT/ID" linkable="true">
    <field XPATH="@ROOT/date">
    <field XPATH="@ROOT/subject_id">
    <field XPATH="@SCAN1/TYPE">
    <field XPATH="@FIELD1/VALUE">
    <field XPATH="@CLIN/cdr/rating" linkable="true">
  </fields>
  <criteria_set METHOD="AND">
     <criteria FIELD="@ROOT/date" comparison=">=" value="1/1/2000"/>
     <criteria_set METHOD="OR">
    <criteria FIELD="@SCAN1/TYPE" value="MPRAGE"/>
    <criteria FIELD="@SCAN1/TYPE" value="T1"/>
     </criteria_set>
  </criteria_set>
</searchAPI>

OUTPUTS:
Results (as CSV, xnat xml documents, or standard XML Listing)

The most common return structure will be the XNAT Search Listing XML.

<results count="">
  <columns>
    <column>ID</column>
    <column>date</column>
    <column>subject_id</column>
    <column>type</column>
    <column>value</column>
    <column>rating</column>
  </columns>
  <row>
   <row>
     <cell ID="0110210_tc0912">0110210_tc0912</cell>
     <cell>1/2/2000</cell>
     <cell>0110210</cell>
     <cell>T1</cell>
     <cell ID="0110210_clin_111200">1</cell>
   </row>
  </row>
</results>


Upload/Download

Store XML
This is the standard interface for storing any XNAT supported xml structure (including custom extensions).

INPUTS:
HTTP Session ID : STRING
XML DOCUMENT : STRING
Allow Data Deletion : BOOLEAN : Whether or not to delete elements not included in this document.

OUTPUTS:
Status : STRING

Retrieve XML
This is a standard structure for downloading a stored XML document.

INPUTS:
HTTP Session ID : STRING
Search Field : STRING (i.e. xnat:MRSession/ID)
Search Value : OBJECT

OUTPUTS:
XNAT XML Document

Store XAR
This service allows users to upload xml files with their corresponding image data. The image files will be moved to the Image Session folder. Any XNAT compliant file references in the corresponding xml documents will be updated with the path of the stored resources. More info...

INPUTS:
HTTP Session ID : STRING
ARCHIVE : FILE (.xnat, .tar or .tar.gz)

OUTPUTS:
Status : STRING


Project Management

Request Projects
This service will return a brief summary of the projects in an XNAT instance. It will include studies which you have permission to see. It will also include projects which you may want to request access to.
URL : HOST/REST/users
INPUTS:
HTTP Session ID : STRING

OUTPUTS:
PROJECTS_XML : XML FILE

<results TITLE="Projects">
 <columns>
   <column DESC="Whether user has permission to access this project">canAccess</column>
   <column DESC="public|protected|private">accessibility</column>
   <column>ID</column>
   <column>name</column>
   <column>description</column>
 </columns>
 <rows>
   <row>
     <cell>TRUE</cell>
     <cell>protected</cell>
     <cell>TEST1</cell>
     <cell>First Test Project</cell>
     <cell>A detailed description</cell>
   </row>
 </rows>
</results>

Request Project Access
This service allows users to request access to a project. Based on the supplied project name, an email will be sent to the owners of the project requesting access to the project. The project owners can then approve or deny the request. The user will receive an email when the request has been resolved.

INPUTS:
HTTP Session ID : STRING
Project : STRING
Level : STRING (owner|member|collaborator) OPTIONAL - defaults to collaborator

OUTPUTS
Status : STRING

Create project
This services allows users to remotely create a new project. After creating the project, the server will also setup the owner, member, and collaborator groups as well as the default search for each specified data type.

<xnat:Project ID="TIM2" name="Tim&amp;apos;s Second Test" secondary_ID="TIM TEST 2">
   <xnat:studyProtocol ID="TIM2_xnat_subjectData" name="Subjects" data-type="xnat:subjectData" xsi:type="xnat:datatypeProtocol">
        <xnat:definitions>
            <xnat:definition ID="default" data-type="xnat:subjectData" description="Basic demographics" project-specific="0">
                <xnat:fields>
                    <xnat:field name="Date of Birth" type="standard" datatype="date" required="0" xmlPath="xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/dob"/>
                    <xnat:field name="Gender" type="standard" datatype="string" required="0" xmlPath="xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/gender">
                        <xnat:possibleValues>
                            <xnat:possibleValue>male</xnat:possibleValue>
                            <xnat:possibleValue>female</xnat:possibleValue>
                            <xnat:possibleValue>unknown</xnat:possibleValue>
                        </xnat:possibleValues>
                    </xnat:field>
                    <xnat:field name="Handedness" type="standard" datatype="string" required="0" xmlPath="xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/handedness">
                        <xnat:possibleValues>
                            <xnat:possibleValue>left</xnat:possibleValue>
                            <xnat:possibleValue>right</xnat:possibleValue>
                            <xnat:possibleValue>ambidextrous</xnat:possibleValue>
                            <xnat:possibleValue>other</xnat:possibleValue>
                        </xnat:possibleValues>
                    </xnat:field>
                    <xnat:field name="Race" type="standard" datatype="string" required="0" xmlPath="xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/race"/>
                    <xnat:field name="Ethnicity" type="standard" datatype="string" required="0" xmlPath="xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/ethnicity"/>
                </xnat:fields>
            </xnat:definition>
        </xnat:definitions>
    </xnat:studyProtocol>
    <xnat:studyProtocol ID="TIM2_xnat_petSessionData" name="PET Sessions" data-type="xnat:petSessionData" xsi:type="xnat:datatypeProtocol">
        <xnat:definitions>
            <xnat:definition ID="default" data-type="xnat:petSessionData" project-specific="0"/>
        </xnat:definitions>
    </xnat:studyProtocol>
    <xnat:studyProtocol ID="TIM2_xnat_mrSessionData" name="MR Sessions" data-type="xnat:mrSessionData" xsi:type="xnat:datatypeProtocol">
        <xnat:definitions>
            <xnat:definition ID="default" data-type="xnat:mrSessionData" project-specific="0"/>
        </xnat:definitions>
    </xnat:studyProtocol>
</xnat:Project>

INPUTS:
HTTP Session ID : STRING
PROJECT XML : XML STRING (xnat:Project from xnat.xsd)

OUTPUTS:
Status : STRING

HTTP METHOD
URI
REQUEST
RESPONSE
GET
/users?format=[xnat | xml_list]

xml_list (xdat:user)
POST
/users/VALUE[email | login]
xml (xdat:user)
integer:xdat:user_id
GET
/users/VALUE[email | login | xdat_user_id]?format=[xnat | xml_list]

xml_list (xdat:user)
POST
/projects/VALUE[ID]
xml (xnat:Project)
string:ID
GET
/projects?format=[xnat | xml_list]

xml_list (xnat:Project)
GET
/projects/VALUE[ID]?format=[xnat | xml_list]

xml_list (xnat:Project)
GET
/projects/VALUE[ID]/users

xml_list (xdat:user + group)
GET
/projects/VALUE[ID]/users/VALUE[owner|member|collaborator]

xml_list (xdat:user + group)
POST
/projects/VALUE[ID]/users/VALUE[owner|member|collaborator]/VALUE[xdat_user_id|login|email]

xml_list (xdat:user + group)
DELETE
/projects/VALUE[ID]/users/VALUE[owner|member|collaborator]/VALUE[xdat_user_id|login|email]

xml_list (xdat:user + group)