icon-toolbox.png
XNAT Tools


Client Tools


XNAT Desktop


XNAT DICOM Gateway


Web Services


Web Services: XNAT Rest API


Web Services: Examples

[Edit Nav] ]

This document specifies the web services API for the XNAT file server, still in early development

XNAT Desktop File Repository Web Services


In all methods listed below, resource data is moved as raw data, while metadata is moved as XML. If multiple entities (i.e., both resource data and URIs/metadata) are carried in a single HTTP message, an appropriate MIME encapsulation will be used.

Security methods (authentication, transport encryption, and permissions) are not yet specified. Eventually, we'll probably want all messages (except possibly initial credentials exchange) over SSL/TLS, and use the standard HTTP authorization metadata for session management. There will be no security model for the initial implementation.

So far there is no way to use search results to make metadata changes without actually exchanging all of the URIs involved; it might be nice to be able to say, "for any file where project=proj1, change that to proj1a," without having to enumerate the gazillion URIs.

Also, there's no version indicator on the API, which mean we're promising backwards compatibility forever. I haven't yet found good examples of how to specify a version for a web services API; any examples would be appreciated.

The XML formats used in the operations below are specified in the following schema documents:

http://nrg.wustl.edu/svn/xnat-engine/server/trunk/src/main/resources/xnat-metadata.xsd
http://nrg.wustl.edu/svn/xnat-engine/server/trunk/src/main/resources/xnat-labels.xsd
http://nrg.wustl.edu/svn/xnat-engine/server/trunk/src/main/resources/xnat-search.xsd

A table documenting the HTTP methods is here:

http://nrg.wustl.edu/svn/xnat-engine/server/trunk/src/site/methods.html

Operations on resources


Upload

Uploads a resource (data file) for storage in the repository, optionally assigning associated metadata (tags).

URI: /data
HTTP method: POST
request contents: data, metadata (both optional)
response contents: URI for newly created resource

or

URI: requested URI for resource (must start with /data)
HTTP method: PUT
request, response contents: same as POST above

A POST or PUT request may contain data, metadata, or both. If the request contains only one component, it may be sent as the request entity with appropriate Content-Type (any type for data, or application/x-xnat-metadata+xml for metadata); the metadata component should also have Content-Disposition=x-xnat-metadata. If the request contains more than one component (e.g., data plus metadata), the request entity must be Content-Type multipart using MIME to encapsulate the components, with each part using Content-Type and Content-Disposition as for the single-part request entity above.

Example metadata specification:
<tags>
<tag label="project">
<value>my-project</value>
</tag>
<tag label="keywords">
<value>example</value>
<value>web API</value>
</tag>
</tags>


Download

Retrieves a resource (data file) from the repository, optionally with its associated metadata.

HTTP method: GET
URI: resource-uri | resource-uri?no-data | resource-uri?no-metadata
request contents: none
response contents: data (unless otherwise specified), metadata (unless otherwise specified)

Metadata values will be in the same format as in the Upload example above. For data, Content-Type will be the content type specified at POST time (or application/octet-stream if none was specified) and Content-Disposition will be inline. For metadata, Content-Type=x-xnat-metadata+xml and Content-Disposition=x-xnat-metadata.

We intend to provide a partial-path virtual directory listing: if the requested resource does not exist, the server will search for resources with URIs starting with the requested URI. This is best explained by example: given the following registered resources:
/data/foo/bar/baz.txt
/data/foo/bar/quack/moo.dat
/data/foo/bar/quack/oink.dat

the response for requested URI /data/foo/bar is one resource and another virtual directory:

<html>
<a href="baz.txt">baz.txt</a>
<a href="quack">quack</a>
</html>

(Some XHTML formalities have been omitted here for clarity.)

If the query string ?recursive is added to the request, a full recursive listing is provided, so the response is:

<html>
<a href="baz.txt">baz.txt</a>
<a href="quack/moo.dat">quack/moo.dat</a>
<a href="quack/oink.dat">quack/oink.dat</a>
</html>

If no resources have paths starting with the requested URI, then the expected HTTP error code 404 is returned.

The partial-path listing service is not yet implemented.

Modify

Replaces data or metadata for an existing resource.

HTTP method: PUT
URI: resource-uri
request contents: data (optional), metadata (optional)
response contents: none

If one component is included, the component may be transported as the request entity. If more than one component is included, the Content-Type must be multipart and the components encoded as a MIME message. Content-Type and Content-Disposition should be set as for POST.

Example metadata specification:
<tags>
<tag label="keywords">
<value>new value</value>
<value delete="value to be deleted" />
<value replace="old value">replacement</value>
</tag>
<delete label="old"/>
</tags>

Delete

Removes a resource and its associated metadata from the repository.

HTTP method: DELETE
URI: resource-uri
request contents: none
response contents: none


Searching operations


HTTP method: GET
URI: /search?label1=value1&label2=value2&...&labeln&...&?labelm&...

request contents: none
response contents: URIs of matching resources, all values of unassigned tags given the value constraints

Notes on search semantics:

Tags for which both label and value are set are searching for an exact match to that tag. We will probably want a pattern-matching operation as well, to be defined later.
A tag label t may be constrained to multiple values v1, v2, ..., in which case a URI is returned only if its tag t contains all the values v1, v2, ... . A tag label with no value is a constraint that the tag must be set (to any value) in matching resources. A tag label preceded by ? generates a search on values of the named tag, so that (1) only URIs for resources that have no values assigned to the named tag will be returned, and (2) all values for the named tag assigned to resources that match the other tag constraints will be returned in the response.
Values may contain URL-unsafe characters that must be properly escaped. (Tag labels cannot contain anything URL-unsafe.)


HTTP method: POST
URI: /search
request contents: XML specification of search parameters

This method, allowing more complex searches will be defined and implemented later.


HTTP method: PUT
URI: /search?label1=value&...
request contents: XML specification of metadata changes for matching resources

Seems like a good idea to eliminate some moving around of big lists of URIs. Should be reviewed to see if we'll actually use it.


Operations on tags


Define


Defines a new tag label.

HTTP method: POST
URI: /tag/label

Find


Determines whether a tag label is defined.

HTTP method: GET
URI: /tag/label

If no labels are provided, an XML file listing all defined tags is returned.

Delete


Deletes an existing tag label and all associated values.

HTTP method: DELETE
URI: /tag/label