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.

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
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

{
  "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.

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)


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
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

{
  "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.

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
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

Response

{
  "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

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

{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


{project-id}Optional (but common) path parameter
format

Optional querystring parameter

  • xml (default)
  • html
  • json
  • csv

Response

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

{
  "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.


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.
xsiTypeRequired 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

201Created
403Permission Denied – User does not have permission to create data in this project
404Not Found – Project ID not recognized
417Expectation Failed – No xsiType parameter was specified, XNAT cannot parse the experiment data
422Unprocessable 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:

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

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}Experiment Data REST XML Path Shortcuts

Response Codes

200Experiment Modified
403Forbidden (i.e. the logged-in user does not have permission to modify data to this project)
422Unprocessable 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:

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.

labelOptional 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

200OK
403Forbidden (User does not have permission to perform the requested operation)
404Project Not Found
409Conflict 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

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.

{
  "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

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
removeFilesOptional 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

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

Response Format: none

  • No labels