Experiment API

Related

Get All Experiments In XNAT

This API call is essentially a search of one or more data types, and is formatted to return a table of results.

Note: You can set this API to return paged results via the "limit" and "offset" settings. See Paging RESTful tables

CODE

GET - /data/experiments

Parameters

format	Optional querystring parameter json (default) xml html csv
columns	Optional querystring parameter, specifying specific columns via Experiment Data REST XML Path Shortcuts. Always included: ID URI Included by default if no columns are specified: date insert_date label project xsiType
limit	Used to page the results returned. This setting chooses the number of rows to return. Note: Adding 'limit=*' will force all results to be returned. If you are encoding a reference to this API in a script and expect all results to be returned, add this parameter to insure it. In later releases, the default behavior of this url could change.
offset	Used to page the results returned. This setting controls the number of rows to skip. With a limit of 100, then page 1 would be offset=0, page 2 would be offset=100, page 3 would be offset 200, etc
date	Optional querystring parameter – can be used to restrict the search to a single date or a date range. The date must be formatted as MM/DD/YYYY. Example: `?date=01/01/2017` `?date=01/01/2017-01/01/2018`
{param}	Optional querystring parameter – can be used to restrict the search by any string parameter listed in Experiment Data REST XML Path Shortcuts, using a wildcard string search. Example: `?xsiType=xnat:mrSessionData` `?ID=XNAT_E0001` `?label=GSU001_v_mr` `?UID=1.2.` `?modality=PT`

Response

CODE

{
  "ResultSet": {
    "Result": [
      {
        "date": "",
        "xsiType": "xnat:mrSessionData",
        "insert_date": "datetime",
        "project": "string {project-id}",
        "ID": "string {experiment-id}",
        "label": "string {experiment-label}",
        "URI": "path"
      },
      ...
    ],
    "totalRecords": "integer",
    "title": "Matching experiments"
  }
}

Get All Experiments In A Project

This API call is essentially a search of one or more data types, and is formatted to return a table of results.

Note: You can set this API to return paged results via the "limit" and "offset" settings. See Paging RESTful tables

This API call only returns experiments that are subject assessors (i.e. image sessions, clinical examinations), not experiment assessors (i.e. QC assessors, Freesurfer outputs)

CODE

GET - /data/projects/{project-id}/experiments

Parameters

{project-id}	Required path parameter
format	Optional querystring parameter json (default) xml html csv
columns	Optional querystring parameter, specifying specific columns via Experiment Data REST XML Path Shortcuts. Always included: ID URI Included by default if no columns are specified: date insert_date label project xsiType
limit	Used to page the results returned. This setting chooses the number of rows to return. Note: Adding 'limit=*' will force all results to be returned. If you are encoding a reference to this API in a script and expect all results to be returned, add this parameter to insure it. In later releases, the default behavior of this url could change.
offset	Used to page the results returned. This setting controls the number of rows to skip. With a limit of 100, then page 1 would be offset=0, page 2 would be offset=100, page 3 would be offset 200, etc
date	Optional querystring parameter – can be used to restrict the search to a single date or a date range. The date must be formatted as MM/DD/YYYY. Example: `?date=01/01/2017` `?date=01/01/2017-01/01/2018`
{param}	Optional querystring parameter – can be used to restrict the search by any string parameter listed in Experiment Data REST XML Path Shortcuts, using a wildcard string search. Example: `?xsiType=xnat:mrSessionData` `?ID=XNAT_E0001` `?label=GSU001_v_mr` `?UID=1.2.` `?modality=PT`

Response

CODE

{
  "ResultSet": {
    "Result": [
      {
        "date": "",
        "subject_label": "string",
        "insert_date": "datetime",
        "project": "string {project-id}",
        "ID": "string {experiment-id}",
        "label": "string {experiment-label}",
        "URI": "path"
      },
      ...
    ],
    "totalRecords": "integer",
    "title": "Matching experiments"
  }
}

Get All Experiments For A Subject

This API call is essentially a search of one or more data types, and is formatted to return a table of results.

CODE

GET - /data/projects/{project-id}/subjects/{subject-label | subject-id}/experiments

Parameters

{project-id}

Required path parameter

{subject-label} or {subject-id}

Required path parameter

format

Optional querystring parameter

json (default)
xml
html
csv

Response

CODE

{
  "ResultSet": {
    "Result": [
      {
        "date": "",
        "ID": "string {experiment-id}",
        "insert_date": "datetime",
        "label": "string {experiment-label}",
        "project": "string {project-id}",
        "URI": "path",
        "xnat:subjectassessordata/id": "string {experiment-id}",
        "xsiType": "string"
      },
      ...
    ],
    "totalRecords": "integer",
  }
}

Get A Single Experiment Record

This API call returns a much more detailed experiment record, including child data that is owned by the experiment, including scans and assessors

CODE

GET - /data/experiments/{experiment-id}
GET - /data/projects/{project-id}/experiments/{experiment-label | experiment-id}
GET - /data/projects/{project-id}/subjects/{subject-label | subject-id}/experiments/{experiment-label | experiment-id}

Parameters

{project-id}	Optional (but common) path parameter
{experiment-id} or {experiment-label}	Required path parameter. experiment-label is a project-specific field and can only be used if project-id is also specified
{subject-id} or {subject-label}	Optional (but common) path parameter. subject-label is a project-specific field and can only be used if project-id is also specified
format	Optional querystring parameter html (default as of 1.8.7) xml (default prior to 1.8.7) json csv

Response

Example of a JSON output on a query of an image session

CODE

{
  "items": [
    {
      "children": [
        {
          "field": "assessors/assessor",
          "items": [ ... ]
        },
        {
          "field": "scans/scan",
          "items": [ ... ]
        }
      ],
      "meta": {
        "create_event_id": integer,
        "xsi:type": "xnat:mrSessionData",
        "isHistory": boolean,
        "start_date": "UTC datetime"
      },
      "data_fields": {
        "acquisition_site": "string",
        "date": "{YYYY-MM-DD}",
        "dcmAccessionNumber": ".",
        "dcmPatientBirthDate": "{YYYY-MM-DD}",
        "dcmPatientId": "string {experiment-label}",
        "dcmPatientName": "string {subject-label}",
        "fieldStrength": "float",
        "ID": "string {experiment-id}",
        "id": "string {experiment-id}",
        "label": "string {experiment-label}",
        "modality": "MR",
        "prearchivePath": "path",
        "project": "string",
        "scanner": "string",
        "scanner/model": "string",
        "scanner/manufacturer": "string",
        "subject_ID": "string {subject-id}",
        "session_type": "string {project-id}",
        "time": "{HH:MM:SS}",
        "UID": "string"
      }
    }
  ]
}

Create A New Experiment

Use this call to create a new experiment record in a project, where the specified experiment label is not already in use.

Some sort of XNAT xsiType parameter must be specified in the request, either in the body or the querystring, for this PUT request to succeed. Otherwise, XNAT has no way of matching your experiment data to a known data type.

CODE

PUT - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-label}

Parameters

{project-id}	Required path parameter
{subject-id} or {subject-label}	Required path parameter. If you specify a subject that does not exist yet in this project, a new subject will be created using your input as the subject label.
{experiment-label}	Required path parameter. This is the label that your new experiment will be given.
xsiType	Required querystring parameter. The value attached to the xsiType should match a known XSD datatype, i.e. "xnat:mrSessionData"
{param}	Required body or querystring parameter. You can use shortcuts specified in Experiment Data REST XML Path Shortcuts. Include XML or JSON experiment definition in the body of your PUT request Include a parameter key/value pair in the querystring – i.e. `?xnat:mrSessionData/date=01/01/2018`

Response Codes

201	Created
403	Permission Denied – User does not have permission to create data in this project
404	Not Found – Project ID not recognized
417	Expectation Failed – No xsiType parameter was specified, XNAT cannot parse the experiment data
422	Unprocessable Entity – Unknown xsiType parameter was specified, XNAT cannot parse the experiment data

Response Format

On 201 - Success, the response is a simple string of the new experiment's accession ID. For example:

CODE

XNAT_E00067

Modify An Experiment Record's Metadata

This is the same URI as in creating the experiment record. The only difference is that now the experiment label exists in this project and can be modified. You can set values for an existing subject record by appending XML path shortcuts as querystring parameters to the end of the PUT request

CODE

PUT - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}

Parameters

{project-id}	Required path parameter
{subject-id} or {subject-label}	Required path parameter
{experiment-label}	Required path parameter
{params}	Optional querystring parameters. See Experiment Data REST XML Path Shortcuts
{functions}	Optional querystring parameters that specify functions. See Experiment API Utility Functions

Response Codes

200	Experiment Modified
403	Forbidden (i.e. the logged-in user does not have permission to modify data to this project)
422	Unprocessable Entity (i.e. the supplied project ID could not be resolved)

Response Format
The response from a successful experiment record modification is a simple string displaying the subject's XNAT accession ID. For example:

CODE

XNAT_E00067

Share An Experiment Into A New Project

Sharing an experiment by itself has no effect if the subject that owns the experiment is not also shared.

PUT - /data/projects/{original-project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/projects/{shared-project-id}

Parameters

{original-project-id}	Required path parameter. Specify the ID of the project that owns a given subject.
{subject-id} or {subject-label}	Required path parameter.
{experiment-id} or {experiment-label}	Required path parameter.
{shared-project-id}	Required path parameter. Specify the ID of the project that you intend a subject to be shared into. Logged-in user must have ownership permissions in the shared project.
label	Optional querystring parameter. Specify a new label for this experiment that will be used in the shared project, if desired.
primary	Optional querystring parameter. If set to "true", you are changing the primary ownership of the experiment from the original project to the new project. Logged-in user must have ownership permissions in both projects to change the primary ownership.

Response Codes

200	OK
403	Forbidden (User does not have permission to perform the requested operation)
404	Project Not Found
409	Conflict Found – Attempting to share data into an object that already exists

Response Format

Returns the experiment accession ID as a string

Get A List Of Shared Projects Associated With An Experiment

CODE

GET - /data/projects/{original-project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-id | experiment-label}/projects

Parameters

{original-project-id}	Required path parameter. Specify the ID of the project that owns a given subject.
{subject-id} or {subject-label}	Required path parameter.
{experiment-id} or {experiment-label}	Required path parameter.
format	Optional querystring parameter. Specify the format of the returned response. html (default) json xml csv

Response

Displaying JSON results. Note that the response does not specify which project owns an experiment.

CODE

{
  "ResultSet": {
    "Result": [
      {
        "label": "string",
        "ID": "string",
        "Secondary_ID": "string",
        "Name": "string"
      },
      ...
    ]
  }
}

Delete (Or Unshare) An Experiment Record

Performing this call in a project that owns an experiment record will permanently delete the experiment data from your project and your XNAT archive.

Performing this call in a project that this experiment has been shared into will simply delete the sharing relationship – no data will be deleted from your XNAT archive, it will simply be removed from this project

CODE

DELETE - /data/projects/{project-id}/subjects/{subject-id | subject-label}/experiments/{experiment-label}

Parameters

{project-id}	Required path parameter
{subject-id} or {subject-label}	Required path parameter
{experiment-label}	Required path parameter. To delete or remove an experiment, you must specify an existing experiment label in this project
removeFiles	Optional query param. Defaults to "FALSE", which will leave files in the file system after deleting the experiment record in Postgres. When this param is set to "TRUE", those files are permanently deleted.

Response Codes

200	Subject Deleted
403	Forbidden (i.e. the logged-in user does not have permission to delete data in this project)
422	Unprocessable Entity (i.e. the supplied project ID or subject ID could not be resolved)

Response Format: none