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.
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.
returns a list of projects
returns a list of subjects for the given project
returns a list of experiments for a given subject
returns a list of experiments for a project
returns a list of all experiments
returns a list of all subjects
returns a list of scans for an imaging session
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).
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.
Will return all data which extends the xnat:experimentData type (which you have access to).
Will return all experiments which are subject assessors (which you have access to).
Will return all experiments which are imaging sessions (which you have access to)
Will return all MR Sessions (which you have access to)
Warning: Returning all experiments can lead to very large documents.
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).
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.