Skip to main content
Skip table of contents

Legacy XNAT Site 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.

As of XNAT 1.7, there are other means available to store config settings on a site-wide level. 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:

200A site-specific config exists for this tool
404A 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
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 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.

JavaScript errors detected

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

If this problem persists, please contact our support.