Image Assessor Resource API

Related

Image Assessor Resource Organization (IN | OUT)

Image Assessor resource REST API calls support the in and out parameters (see below). Unlike many REST URL parameters, in and out are not processing directives or attribute values, but instead operate as taxonomies to help distinguish the origins of your archived data. This allows for the segregation of resources by their provenance in the generation process:

The in specifier groups files that are used as processing inputs
The out specifier groups files that are generated and output by the processing

This is used often in pipeline processing. For example, when XNAT performs Freesurfer processing on a session, the processing inputs to Freesurfer are put in the in folder. These are usually a collection of files, some of which may not have existed in XNAT. All of the files output by Freesurfer are then placed in the out section. When retrieving processing results, it is often necessary to have the exact files on which the processing was performed.

Placement of resources into the in and out folders can have practical effects other than clarification of provenance. For example, download operations usually ignore the content of the in folders, given that that data usually originates from the acquired data, meaning that the contents of the in folder are really duplicates of the acquired data. Data contained in out folders is included as a download option, since it's assumed that users would want the extrapolated data for further analysis.

Get A Listing Of All Resource Collections Stored With An Image Assessor

CODE

GET - /data/experiments/{session-id}/assessors/{assessor-id}/resources
GET - /data/projects/{project-id}/subjects/{subject-label}/experiments/{session-label}/assessors/{assessor-label}/resources

Parameters

{project-id}	Path parameter
{subject-id} or {subject-label}	Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.
{session-id} or {session-label}	Path parameter. Session label is a project-specific field, and can only be used if a project is specified.
{assessor-id} or {assessor-label}	Path parameter. Assessor label is a project-specific field, and can only be used if a project is specified.
format	Optional querystring parameter. Specify the format of the returned response. json (default) html xml csv
sortBy	Optional querystring parameter: Sort the returned results by one or more parameters in the Result array. Multiple parameters can be provided, separated by commas.

Response

This call returns an array of resource descriptors, where the key values are "xnat_abstractresource_id" and "label", which can be used as a path parameter to return individual resource collections.

CODE

{
  "ResultSet": {
    "Result": [
      {
        "cat_desc": "string",
        "cat_id": "string",
        "category": "assessors",
        "content": "string",
        "element_name": "xnat:resourceCatalog",
        "file_count": "integer",
        "file_size": "integer (bytes)",
        "format": "string",
        "label": "string {resource-label}",
        "tags": "string",
        "xnat_abstractresource_id": "integer {resource-id}"
      }
    ],
    "totalRecords": "integer",
    "title": "Resources"
  }
}

Get A Listing Of All Resource Files Stored With An Assessor

CODE

GET - /data/experiments/{session-id}/assessors/{assessor-id}/files
GET - /data/projects/{project-id}/subjects/{subject-label}/experiments/{session-label}/assessors/{assessor-label}/files

Parameters

{project-id}	Path parameter
{subject-id} or {subject-label}	Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.
{session-id} or {session-label}	Path parameter. Session label is a project-specific field, and can only be used if a project is specified.
{assessor-id} or {assessor-label}	Path parameter. Assessor label is a project-specific field, and can only be used if a project is specified.
format	Optional querystring parameter. Specify the format of the returned response. json (default) html xml csv
sortBy	Optional querystring parameter: Sort the returned results by one or more parameters in the Result array. Multiple parameters can be provided, separated by commas.

Response

This call returns an array of file listings, where each has a unique URI path to the resource file. Note the "out" in the URI path, signifying that the resource is downloadable.

CODE

{
  "ResultSet": {
    "Columns": [
      {
        "key": "URI",
        "serverRoot": ""
      }
    ],
    "Result": [
      {
        "cat_ID": "integer {resource-id}",
        "collection": "string {resource-label}",
        "file_content": "string",
        "file_format": "string",
        "file_tags": "string",
        "digest": "hash",
        "Name": "string {filename}",
        "Size": "integer",
        "URI": "/data/experiments/{session-id}/assessors/{assessor-id}/out/resources/{resource-id}/files/{filename}"
      },
      ...
    ],
    "title": "Files"
  }
}

Create A New Experiment Resource Folder

Note: {resource-label} must be new and unique in this assessor. Once created, resource descriptors cannot be modified.

CODE

PUT - /data/projects/{project-id}/subjects/{subject-label}/experiments/{experiment-label}/assessors/{assessor-label}/resources/{resource-label}
PUT - /data/experiments/{experiment-id}/assessors/{assessor-id}/resources/{resource-label}

Parameters

{project-id}	Required path parameter
{subject-id} or {subject-label}	Required path parameter
{experiment-id} or {experiment-label}	Required path parameter
{resource-label}	Required path parameter. Specify the label of the resource that you want to create. XNAT will automatically assign an ID.
format	Optional querystring parameter. Specify a string format descriptor for this resource folder.
tags	Optional querystring parameter. Specify a comma-separated list of tags for this resource folder.
content	Optional querystring parameter. Specify a string description of the resource folder's content.

Response: None

Get The Contents Of An Image Assessor Resource File

This URI returns the raw contents of a resource file. If your client cannot parse this file's MIME type, it will not provide a usable output. See How To Download Files via the XNAT REST API for help on downloading resources.

CODE

GET - /data/experiments/{session-id}/assessors/{assessor-id}/{in|out}/resources/{resource-id}/files/{filename}
GET - /data/projects/{project-id}/subjects/{subject-label}/experiments/{session-label}/assessors/{in|out}/resources/{resource-label}/files/{filename}

Parameters

{project-id}	Path parameter
{subject-id} or {subject-label}	Path parameter. Subject label is a project-specific field, and can only be used if a project is specified.
{session-id} or {session-label}	Path parameter. Session label is a project-specific field, and can only be used if a project is specified.
{assessor-id} or {assessor-label}	Path parameter. Assessor label is a project-specific field, and can only be used if a project is specified.
{in\|out}	Path parameter. If you don't know this, query the /files API above to find the URI. "out" is the standard grouping for downloadable resources "in" is the standard grouping for resources meant to be consumed by pipelines or other processes
{resource-id} or {resource-label}	Path parameter
{filename}	Path parameter

Response:

RAW file content

Upload A New Experiment Resource File

Notes:

{filename} must be unique within this resource folder, otherwise the file will not be uploaded.
If {resource-id} does not exist in this assessor, it will be automatically created.

CODE

PUT - /data/experiments/{session-id}/assessors/{assessor-id}/{in|out}/resources/{resource-id}/files/{filename}
PUT - /data/projects/{project-id}/subjects/{subject-label}/experiments/{session-label}/assessors/{assessor-label}/{in|out}/resources/{resource-label}/files/{filename}

Parameters

{project-id}	Required path parameter
{subject-id} or {subject-label}	Required path parameter
{experiment-id} or {experiment-label}	Required path parameter
{assessor-id} or {assessor-label}	Required path parameter
{in\|out}	Required path parameter. "out" is the standard grouping for downloadable resources "in" is the standard grouping for resources meant to be consumed by pipelines or other processes
{resource-id} or {resource-label}	Required path parameter. If this resource collection is not already defined, it will be defined automatically by this call.
{filename}	Required path parameter. This will be the name of the file as it is stored in XNAT. It can be different from the original name of your uploaded file.
inbody=true	Optional querystring parameter. Use if including the file in the body of the request as opposed to part of a multi-part form data
file	Required body or form parameter.
format	Optional querystring parameter. Specify a string format descriptor for this resource folder.
content	Optional querystring parameter. Specify a string description of the resource folder's content.

Response Codes

200	OK - File Created
	OK - Duplicates Existing File (File not created or updated)
	OK - User does not have permission to upload files (File not created or updated)

Update An Existing Image Assessor Resource File

CODE

POST - /data/experiments/{session-id}/assessors/{assessor-id}/{in|out}/resources/{resource-id | resource-label}/files/{filename}?overwrite=true

Parameters

{session-id}	Required path parameter
{assessor-id}	Required path parameter
{in\|out}	Required path parameter. "out" is the standard grouping for downloadable resources "in" is the standard grouping for resources meant to be consumed by pipelines or other processes
{resource-id} or {resource-label}	Required path parameter.
{filename}	Required path parameter. This must match an existing file name as it is stored in XNAT.
overwrite=true	Required querystring parameter. This must be set to allow your new file to overwrite your existing one
file	Required body parameter
inbody=true	Optional querystring parameter. Use if including the file in the body of the request as opposed to part of a multi-part form data

Response Codes

200	OK

Delete An Image Assessor Resource Collection

This URI will also delete all resource files in the collection

CODE

DELETE - /data/experiments/{session-id}/assessors/{assessor-id}/{in|out}/resources/{resource-id | resource-label}

Parameters

{session-id}	Required path parameter
{assessor-id}	Required path parameter
{in\|out}	Required path parameter. "out" is the standard grouping for downloadable resources "in" is the standard grouping for resources meant to be consumed by pipelines or other processes
{resource-id} or {resource-label}	Required path parameter.

Response Codes

200	OK
403	Forbidden

Response: None

Delete An Image Assessor Resource File

CODE

DELETE - /data/experiments/{session-id}/assessors/{assessor-id}/{in|out}/resources/{resource-id | resource-label}/files/{filename}

Parameters

{session-id}	Required path parameter
{assessor-id}	Required path parameter
{in\|out}	Required path parameter. "out" is the standard grouping for downloadable resources "in" is the standard grouping for resources meant to be consumed by pipelines or other processes
{resource-id} or {resource-label}	Required path parameter.
{filename}	Required path parameter. This must match an existing file name as it is stored in XNAT.

Response Codes

200	OK
403	Forbidden

Response: None