Skip to main content
Skip table of contents

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.

JavaScript errors detected

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

If this problem persists, please contact our support.