Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Contents

These API query the user's permissions with the XNAT security model and only return results that the user has permission to access, or to modify.


Get All Subjects In XNAT

This API call is essentially a search of a single data type, and is formatted to return a table of results.

GET - /data/subjects

Parameters:

format

Optional querystring parameter

  • json (default)
  • xml
  • html
  • csv
columns

Optional querystring parameter, specifying specific columns via Subject Data REST XML Path Shortcuts.

Always included:

  • ID
  • URI

Included by default if no columns are specified:

  • insert_date
  • insert_user
  • project
  • label

Response:

{
  "ResultSet": {
    "Result": [
      {
        "insert_date": "datetime",
        "project": "string",
        "ID": "string",
        "label": "string",
        "insert_user": "string",
        "URI": "string"
      },
      ...
    ],
    "totalRecords": "integer"
  }
}


Get All Subjects In A Project

This API call is essentially a search of a single data type, and is formatted to return a table of results.

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

Parameters:

format

Optional querystring parameter

  • json (default)
  • xml
  • html
  • csv
columns

Optional querystring parameter, specifying specific columns via Subject Data REST XML Path Shortcuts.

Always included:

  • ID
  • URI

Included by default if no columns are specified:

  • insert_date
  • insert_user
  • project
  • label

Response:

{
  "ResultSet": {
    "Result": [
      {
        "insert_date": "datetime",
        "project": "string",
        "ID": "string",
        "label": "string",
        "insert_user": "string",
        "URI": "string"
      },
      ...
    ],
    "totalRecords": "integer"
  }
}

Get A Single Subject Record

This API call returns a much more detailed subject record, including child data that is owned by the subject.

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

Parameters

{subject-id} or {subject-label}

Required path parameter.

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

  • json (default)
  • xml
  • html
  • csv

Response

The response object contains a representation of the subject's metadata, its sharing attributes, as well as a representation of the subject's experiments and those experiments' children.

 Show Response Format
{
  "items": [
    {
      "children": [
        {
          "field": "demographics",
          "items": [
            {
              "children": [],
              "meta": {
                "create_event_id": integer,
                "xsi:type": "xnat:demographicData",
                "isHistory": false,
                "start_date": "UTC datetime"
              },
              "data_fields": {
                "education": integer,
                "xnat_abstractDemographicData_id": integer,
                "gender": "string",
                "xnat_abstractdemographicdata_id": integer,
                "handedness": "string",
                "yob": integer
              }
            }
          ]
        },
        {
          "field": "sharing/share",
          "items": [
            {
              "children": [],
              "meta": {
                "create_event_id": integer,
                "xsi:type": "xnat:projectParticipant",
                "isHistory": false,
                "start_date": "UTC datetime"
              },
              "data_fields": {
                "subject_ID": "string",
                "project": "string",
                "label": "string",
                "xnat_projectParticipant_id": integer
              }
            }
          ]
        },
        {
          "field": "experiments/experiment",
          "items": [
            {
              "children": [
                {
                  "field": "sharing/share",
                  "items": [ ... ]
                },
                {
                  "field": "scans/scan",
                  "items": [ ... ]
                }
              ]
            }
          ]
        }
      ],
      "data_fields": {
        "ID": "string",
        "label": "string",
        "project": "string"
      },
      "meta": {
          "create_event_id": integer,
          "xsi:type": "xnat:projectParticipant",
          "isHistory": false,
          "start_date": "UTC datetime"
      }
    }
  ]
}


Create A New Subject Record

Use this call to create a new subject record in a project, where the subject label you intend to create is not already in use.

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

Parameters

{project-id}Required path parameter
{subject-label}Required path parameter. When creating a new subject, this is the label that will appear in search tables.

Response Codes

201Subject Created
403Forbidden (i.e. the logged-in user does not have permission to add data to this project)
422Unprocessable Entity (i.e. the supplied project ID could not be resolved)

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

XNAT_S00036

Modify A Subject Record

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-label}?{params}

Parameters

{project-id}Required path parameter
{subject-label}Required path parameter. To modify a subject, you must specify an existing subject label in this project
{params}Subject Data REST XML Path Shortcuts

Response Codes

200Subject 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 subject record modification is a simple string displaying the subject's XNAT accession ID. For example:

XNAT_S00036

Delete (Or Unshare) A Subject Record

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

Performing this call in a project that this subject 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-label}

Parameters

{project-id}Required path parameter
{subject-label}Required path parameter. To delete a subject, you must specify an existing subject 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 could not be resolved)

Response Format:
None

  • No labels