XNAT REST Session Management

Each REST transaction can result in the instantiation of a new HTTP Session. If you are re-logging in each time you interact with XNAT, this can get expensive. If you are making a limited number of calls to the REST API, then this is not a problem. However, if you are making hundreds or thousands of calls to the REST API in a short period of time, this can look disturbingly like a Denial of Service attack and cause un-necessary processing time.

To compensate for this potential issue, XNAT provides for the use of server side sessions. (We realize this breaks a strict definition of REST, but... to bad). XNAT leverages Java's inherent session management controls to facilitate session based interaction.

To instantiate a new HTTP Session on the server, POST to HOST/data/JSESSION. You must include your login credentials according to the guidelines of your connection tool. The message body returned from this post will contain your SESSION id (a 32 hexi-decimal string). In all subsequent calls this SESSION id must be attached to your HTTP message as a header variable with header name 'JSESSIONID'. You do NOT have to include your login credentials in any message where you have a valid HTTP Session specified. Your user account is tracked via the SESSION ID.

Here are some examples of how the JSESSIONID parameter can be attached to your message:

-user_session AAAABBBBCCCC00001111222233334444

--cookie JSESSIONID=AAAABBBBCCCC00001111222233334444

Java HTTPClient

org.apache.commons.httpclient.HttpMethodBase some_name = new org.apache.commons.httpclient.methods.GetMethod(uri);
String http_session_id="AAAABBBBCCCC00001111222233334444";
some_name.addRequestHeader("Cookie", "JSESSIONID=" + http_session_id);


java.net.URLConnection url = new java.net.URL(uri).openConnection();
String http_session_id="AAAABBBBCCCC00001111222233334444";
url.setRequestProperty("Cookie", "JSESSIONID=" + http_session_id);