Filtering Query on REST API

[benjamin thyreau]

Hi,
Is it possible to use the xpath-like filter when retrieving data ?
ie. having query such as :
/REST/projects/YOURTEST/subjects?xnat:subjectData/demographics
[@xsi:type=xnat:demographicData]/gender=male&xnat:subjectData/
demographics[@xsi:type=xnat:demographicData]/handedness=left"
on a GET call..
Thanks

[Timothy Olsen]

The GET on the subjects level does not currently support the use of filters. I fully intend to support it, but we haven't had time to implement it.

You can use the REST based search engine to do this kind of query. Build a search xml and POST it to HOST/REST/search. You could build a document that would return the same fields the default REST API would.


Here's a quick example...

<?xml version="1.0" encoding="UTF-8"?>
<xdat:bundle ID="" xmlns:xdat="http://nrg.wustl.edu/security" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<xdat:root_element_name>xnat:subjectData</xdat:root_element_name>
<xdat:search_field>
<xdat:element_name>xnat:subjectData</xdat:element_name>
<xdat:field_ID>SUBJECT_LABEL</xdat:field_ID>
<xdat:sequence>0</xdat:sequence>
<xdat:type>string</xdat:type>
<xdat:header>Subject</xdat:header>
</xdat:search_field>
<xdat:search_field>
<xdat:element_name>xnat:subjectData</xdat:element_name>
<xdat:field_ID>PROJECT</xdat:field_ID>
<xdat:sequence>1</xdat:sequence>
<xdat:type>string</xdat:type>
<xdat:header>Project</xdat:header>
</xdat:search_field><xdat:search_field>
<xdat:element_name>xnat:subjectData</xdat:element_name>
<xdat:field_ID>GENDER</xdat:field_ID>
<xdat:sequence>2</xdat:sequence>
<xdat:type>string</xdat:type>
<xdat:header>Gender</xdat:header>
</xdat:search_field>
<xdat:search_where method="AND">
<xdat:criteria>
<xdat:schema_field>xnat:subjectData/GENDER</xdat:schema_field>
<xdat:comparison_type>=</xdat:comparison_type>
<xdat:value>male</xdat:value>
</xdat:criteria>
<xdat:criteria>
<xdat:schema_field>xnat:subjectData/PROJECT</xdat:schema_field>
<xdat:comparison_type>=</xdat:comparison_type>
<xdat:value>PROJECT_NAME</xdat:value>
</xdat:criteria>
</xdat:search_where>
</xdat:bundle>



The search engine uses the display fields defined in the display.xml documents. These are usually auto-generated, but you can modify them to add additional search fields. Unfortunately, I haven't had time to put together documentation for the REST based search engine yet, but it is fairly self explanatory. But there is documentation of the display documents http://nrg.wikispaces.com/XNAT+Display+Documents.

The root_element_name specifies what the data type you are searching for is. There will be one row per data instance of this type. The search_fields specify the columns to return. The XSD for the search xml is included with XNAT, security/security.xsd.

Hope this helps.
Tim

[Alexis]

Hi Tim,

I just has a look to this, and I have a basic question : how do you
run such searches ? I mean I saw in the REST API wiki page the "search
management" section, but all I can get is a description of a saved
search ( like for instance CENTRAL_OASIS_CS_xnat_subjectData ), not
the results.

I have an unrelated question : does the xnat security system is used
in the REST system ? I just noticed that with the "users" function,
any registered user could get all users id and email.

Alexis

> The search engine uses the display fields defined in the display.xml documents.  These are usually auto-generated, but you can modify them to add additional search fields. Unfortunately, I haven't had time to put together documentation for the REST based search engine yet, but it is fairly self explanatory.  But there is documentation of the display documentshttp://nrg.wikispaces.com/XNAT+Display+Documents.

[Timothy Olsen]

Security is enforced on the projects/subjects/experiments/etc through the REST API. The list of users is currently not secured. This allows any user to poll the list of users and add some of them to their projects (an important feature of the project page).

To retrieve search results, you need to POST the search xml document to HOST/REST/search. This should return the search results.

[benjamin thyreau]

Hi,
I keep getting some error message, such as
<h3>The server understands the content type of the request entity and
the syntax of the request entity is correct but was unable to process
the contained instructions</h3><p>You can get technical details <a
href="http://www.webdav.org/specs/rfc2518.html#STATUS_422">here</
a>.<br>
Please continue your visit at our <a href="/">home page</a>.
</p>

I'm using the commandline tool
./XNATRestClient -u benjamin -p xxxxxxx -host http://central.xnat.org -
m POST -remote '/REST/search' -local ./test3.xml
with test3.xml being your above file or similar...
Am i doing something wrong ?

[Timothy Olsen]

I'll be updating Central with the newest code on Monday. Lets hold off on this until after that, so we can see if it is resolved in the new code.

I'll be posting to the discussion group when its ready to go.

[roman....@gmail.com]

Hi Tim, 

I have copied the xml from above and saved it into an testsearch.xml file and then tried to run the following command  from a terminal on a local xnat instance (dockerised, version 1.8.9.2):

curl -X POST -d @testsearch.xml -u admin:xxxxx "http://127.0.0.1/data/search?format=csv"

However, I keep receiving the message "The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions. You can get technical details. STATUS_422" 

I also tried to use xml code extracted from a stored search results inside xnat (Options -> Show XML -> copy & paste) but still receive the same message. 

Interestingly, using the GET /data/search/saved/{id}/results endpoint for the above everything works fine.  

Am I passing the .xml in the correct way?

Sandro