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

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:

{project-id}Required path parameter
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


Share Subject And Its Experiments Into A New Project

PUT - /data/projects/{original-project-id}/subjects/{subject-id | subject-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.
{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 subject 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 subject from the original project to the new project.

Logged-in user must have ownership permissions in both projects to change the primary ownership.

format

Optional querystring parameter. Specify the format of the returned response.

  • html (default)
  • json
  • xml
  • csv

Response Codes

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

Response Format
Returns the subject metadata from the original project



Get A List Of Shared Projects Associated With A Subject

This query will return a list of all projects associated with a subject. The root project ID in the URI can be either a project that owns the subject or a shared project.

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

Parameters

{project-id}Required path parameter
{subject-id} or {subject-label}Required path parameter
format

Optional querystring parameter. Specify the format of the returned response.

  • html (default)
  • json
  • xml
  • csv

Response Format
Displaying JSON results. Note that the response does not specify which project owns a subject.

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




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