Skip to main content
Skip table of contents

Project Configuration API

Contents


Introduction

The XNAT config service is a flexible API that allows individual features and plugins to store or retrieve configuration information as needed. Each feature or plugin that stores a unique config object is referred to as a "tool." These configurations can be stored on a site-wide or project level. Configurations can correspond to a control panel that allows users to directly edit settings, but the information stored in the config API may expand beyond what is displayed in the control panel. Since each tool is unique, this API documentation will only focus on the general functionality associated with storing and retrieving config settings. 

For an example on how to use these API on a core XNAT config setting, see: Using the XNAT API: How to Configure Scan Quality Labels.


Get A Listing Of Tools With Active Configurations At The Project Level

CODE
GET - /data/projects/{projectId}/config

Parameters:

{projectId}Required path parameter
format

Optional querystring parameter. Specifies the output format.

  • json (default)
  • html
  • xml
  • csv

Response:

The response provides a list of tool IDs. Each tool ID can be used as a path parameter to retrieve specific config information about that tool.   

CODE
{
  "ResultSet": {
    "Result": [
      {
        "tool": "string"
      },
      ...
    ]
  }
}


Get A Config Object For A Specific Tool In Your Project

CODE
GET - /data/projects/{project-id}/config/{tool-id}

Parameters:

{project-id}Required path parameter
{tool-id}Required path parameter – uses the same string as listed above in the listing of all config tools
format

Optional querystring parameter. Specifies the output format.

  • json (default)
  • html
  • xml
  • csv


accept-not-found

Optional querystring parameter.

  • true: returns a 204 - Content Not Found code, if no configs have been set for this tool

Response Code:

200A project-specific config exists for this tool
204A project-specific config has never been set for this tool (if accept-not-found = true)
404A project-specific config has never been set for this tool


Response Format:

The inner format of the response for each tool will follow a common structure, but the "contents" parameter may contain a simple string or a complex JSON object, depending on the tool.

CODE
{
  "ResultSet": {
    "Result": [
      {
        "contents": "string",
        "create_date": "datetime",
        "path": "string",
        "reason": "string",
        "project": "string",
        "status": "string",
        "tool": "string",
        "unversioned": "boolean",
        "user": "string",
        "version": "integer"
      },
      ...
    ]
  }
}
Response Parameter
contentsThe actual contents of the configuration file
create_dateThe date/time the configuration was created
paththe path to the configuration file
reasonThe user provided reason for uploading the configuration
statusEnumerated setting: "enabled" / "disabled"
toolThe name of a tool that has configuration files
unversioned

Whether or not this config object is "versioned."

  • If true, new configs will not overwrite old configs, and all versions of a config will be stored.
  • If false, new configs WILL overwrite old configs, and only the latest version of a config will be stored.
userThe user who created the configuration
versionversion number of the configuration contents

Store A Project-specific Config Value For A Specific Tool

CODE
PUT - /data/projects/{project-id}/config/{tool-id}/{file-path}

Parameters

{project-id}Required path parameter
{tool-id}Required path parameter – uses the "tool" string as listed above
{file-path}Required path parameter – uses the "path" string as listed above
inbody

Required querystring parameter

  • "true" indicates that the params object is stored in the body of the PUT request.
contents

Required parameter, either in body or querystring.

The format of your config value should match the format expected by the tool. If you are not sure what that is, perform a GET to get the current value.

Response: No response object is returned. A "201" response code indicates that the config value was stored.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.