Subject API

Related

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.

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

CODE

GET - /data/subjects

Parameters:

Parameter	Description	Format
format	Optional querystring parameter	String: 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	String of comma-separated values
limit	Optional querystring parameter: Returns a single page of paginated results. 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 ensure it. In later releases, the default behavior of this url could change.	Integer
offset	Optional querystring parameter: Returns a single page of paginated results. 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	Integer

Response:

CODE

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

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

CODE

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

Parameters:

Parameter	Description	Format
{project-id}	Required path parameter	String
format	Optional querystring parameter	String 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	String of comma-separated values
limit	Optional querystring parameter: Returns a single page of paginated results. 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 ensure it. In later releases, the default behavior of this url could change.	Integer
offset	Optional querystring parameter: Returns a single page of paginated results. 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	Integer

Response:

CODE

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

CODE

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

Parameters

Parameter

Description

Format

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

String

{project-id}

Optional (but common) path parameter

String

format

Optional querystring parameter

String

html (default)
xml
json
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.

CODE

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

CODE

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

Parameters

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

Response Codes

201	Subject Created
403	Forbidden (i.e. the logged-in user does not have permission to add data to this project)
422	Unprocessable 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:

CODE

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.

CODE

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

Parameters

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

Response Codes

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

CODE

XNAT_S00036

Share Subject And Its Experiments Into A New Project

CODE

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.
label	Optional 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

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

CODE

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.

CODE

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

CODE

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
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 could not be resolved)

Response Format:
None