XNAT Docs Index

Related Pages

 Click here to expand...
Child pages
  • REST Enhanced Listing Options

This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at https://xnat.org/documentation

Skip to end of metadata
Go to start of metadata

The REST Listings in XNAT are a very powerful and versatile tool for navigating the data stored in XNAT. Using the REST listings you can get a dymanic view of your data programmatically. You have the ability to configure which columns are returned and filter the rows returned.

To understand how the REST Listings can be customized, you must first have a sense of the XSD structure which underlies it. The XNAT REST api is based on the data structures defined in the xnat.xsd. There are three core data types in the xnat model; Project, Subject and Experiment. All other data types in XNAT are defined by there relationship to these elements. For more information on the XNAT Data Model review the Understanding the XNAT Data Model section.

Project
Resources/
Subjects/
Resources/
Experiments/
Resources
(Imaging Sessions)
Scans
Resources
Reconstructions
Out
Resources
Assessments
Out
Resources

The REST API allows access to any level of this hierarchy. You can access individual elements. Or you can retrieve listings of the results at any level.

/data/archive/projects

returns a list of projects

/data/archive/projects/ID/subjects

returns a list of subjects for the given project

/data/archive/projects/ID/subjects/ID/experiments

returns a list of experiments for a given subject

/data/archive/projects/ID/experiments

returns a list of experiments for a project

/data/archive/experiments

returns a list of all experiments

/data/archive/subjects

returns a list of all subjects

/data/archive/experiments/ID/scans

returns a list of scans for an imaging session

/data/archive/experiments/ID/reconstructions

returns a list of reconstructions for an imaging session

Each listing returns results of a specific data type. The columns returned by each listing can be customized to return any of the fields defined in the schema for that given data type. The common fields for each data type are specified in the XNAT REST XML Path Shortcuts section. However, you are not limited to only returning the fields specified in that section. Any child element defined in the XNAT for the relevant data-type can be returned (so long as the relationship to the root type is obvious).

xsiType

For resources which can be extended, you can constrain the results to specific data-types. Use the xsiType attribute to limit results to specific types.

/data/archive/experiments?columns=ID,project

Will return all data which extends the xnat:experimentData type (which you have access to).

/data/archive/experiments?columns=ID,project&xsiType=xnat:subjectAssessorData

Will return all experiments which are subject assessors (which you have access to).

/data/archive/experiments?columns=ID,project&xsiType=xnat:imageSessionData

Will return all experiments which are imaging sessions (which you have access to)

/data/archive/experiments?columns=ID,project&xsiType=xnat:mrSessionData

Will return all MR Sessions (which you have access to)

Warning: Returning all experiments can lead to very large documents.

?columns

You can customize the results of a listing by adding the columns attribute as a query string parameter. The following URI would return the default columns for the data-type.

/data/archive/subjects?columns=DEFAULT

If I only wanted to return the ID & project fields, I could specify that using xPath notation (multiple columns should be seperated by commas).

/data/archive/subjects?columns=xnat:subjectData/ID,xnat:subjectData/project

Because these are commonly used fields, I can substitute the XML Path shortcuts for these fields.

/data/archive/subjects?columns=ID,project

But, you are not limited to the fields defined in the XML Path shortcuts. You also aren't limited to fields defined in the root data type. You can actually specify fields from child types as well. WARNING: if you include any columns which are for unbounded elements, you may receive multiple rows for a single instance of the root type.

/data/archive/experiments?format=html&xsiType=xnat:mrSessionData&columns=xnat:mrSessionData/ID,xnat:mrSessionData/project,xnat:mrSessionData/scans/scan/ID,xnat:mrSessionData/scans/scan/type

This will return all MR Sessions with their individual scans.

FYI, In some situations additional columns will be returned (notably the primary key for the data type and the URI to retrieve the data).

Filtering

In the listing interface, you can filter results using the same XML Paths you use to customize the returned columns.

/data/archive/subjects?format=html&columns=ID,project&project=CENTRAL_OASIS_CS

Specify multiple filter parameters to create AND logic. Or, seperate multiple values for a single field with commas to create OR logic.

/data/archive/subjects?format=html&columns=ID,project&project=CENTRAL_OASIS_CS,IGT_GLIOMA

Use * as a wild card in strings.

/data/archive/subjects?format=html&columns=ID,project&project=CENTRAL_*,IGT_GLIOMA

Feel free to experiment with the REST Listing Options and provide feed back to the XNAT Discussion Group (http://groups.google.com/group/xnat_discussion).

Footnote: You can use the columns and filtering parameters in combination with the format tag defined in the XNAT REST API Usage guide.

  • No labels