Legacy XNAT Site Configuration API

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.

There are other means available to store config settings on a site-wide level in modern XNAT versions. The updated Site Admin UI features use /xapi/siteConfig, and other tools make use of /xapi/prefs. Which endpoint you use is largely a matter of convention.

Get A Listing Of Tools With Active Configurations At The Site-wide Level

CODE

GET - /data/config

Parameters:

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 Site

CODE

GET - /data/config/{tool-id}

Parameters:

{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

Response Code:

200	A site-specific config exists for this tool
404	A site-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	Description
contents	The actual contents of the configuration file
create_date	The date/time the configuration was created
path	the path to the configuration file
reason	The user provided reason for uploading the configuration
status	Enumerated setting: "enabled" / "disabled"
tool	The 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.
user	The user who created the configuration
version	version number of the configuration contents

Store A Site-wide Config Value For A Specific Tool

CODE

PUT - /data/config/{tool-id}/{file-path}

Parameters

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