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: