Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel

Contents

Table of Contents

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.

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

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

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

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

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

Note

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.

Note

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

Expand
titleShow Response Format


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

Note

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

Tip

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.
{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 reponse is a simple string of the new experiment's accession ID. For example:

Code Block
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 Block
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:

Code Block
XNAT_E00067




Include Page
Experiment Sharing API
Experiment Sharing API


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

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