Backup API

Overview

The Backup API is an API for referencing and downloading the backup target data of Fess. It allows you to retrieve a list of backup targets and download individual backup files (system properties, bulk data of each index, and NDJSON data of logs).

This API is read-only (reference and download). The restore function for uploading and restoring backup files is not provided through the API; if you need to restore, please use System Info → Backup in the admin UI.

Base URL

/api/admin/backup

Authentication

As with other Admin APIs, authentication using an access token is required. The access token must have the Radmin-api permission (configured via api.admin.access.permissions; the default value is Radmin-api). Specify the access token in the request header.

Authorization: Bearer <access token>

For details on authentication and how to obtain an access token, see Admin API Overview.

Endpoint List

Method Path Description
GET /files Retrieve backup target list
GET /file/{id} Download backup file

Retrieve Backup Target List

Returns a list of backup targets. The targets are based on the index.backup.targets and index.backup.log.targets settings, and a combined list of both is returned.

Request

GET /api/admin/backup/files

Response

files contains an array of objects representing the backup targets, and total contains the count. Each object has id and name, both of which are set to the target name (such as fess_config.bulk, system.properties, or search_log.ndjson).

The following is an example under the default settings (when index.backup.targets and index.backup.log.targets are at their default values).

{
  "response": {
    "version": "15.9",
    "status": 0,
    "files": [
      { "id": "fess_basic_config.bulk", "name": "fess_basic_config.bulk" },
      { "id": "fess_config.bulk", "name": "fess_config.bulk" },
      { "id": "fess_user.bulk", "name": "fess_user.bulk" },
      { "id": "system.properties", "name": "system.properties" },
      { "id": "fess.json", "name": "fess.json" },
      { "id": "doc.json", "name": "doc.json" },
      { "id": "chat_log.ndjson", "name": "chat_log.ndjson" },
      { "id": "click_log.ndjson", "name": "click_log.ndjson" },
      { "id": "favorite_log.ndjson", "name": "favorite_log.ndjson" },
      { "id": "search_log.ndjson", "name": "search_log.ndjson" },
      { "id": "user_info.ndjson", "name": "user_info.ndjson" }
    ],
    "total": 11
  }
}

Note

version is set to the product version of the running Fess. The contents of files vary depending on the index.backup.targets / index.backup.log.targets settings; the above is an example with default values.

Download Backup File

Downloads the contents of the specified backup file. For {id}, specify the id (target name) obtained from the target list retrieval. Depending on the type of {id}, the response content switches as follows.

ID Content
system.properties Contents of the system properties (application/octet-stream)
fess.json / doc.json The index mapping definition file itself (fess_indices/fess.json / fess_indices/fess/doc.json), returned as-is (application/octet-stream)
*.bulk or an index name without an extension Bulk data generated by scrolling the index with the same name as the target (application/octet-stream). The name with .bulk removed is treated as the index name.
*.ndjson (search_log / user_info / click_log / favorite_log / chat_log) NDJSON data of the corresponding log (application/x-ndjson)

Note

This API only downloads. To restore (upload) backup files, including fess.json and doc.json, use System Info → Backup in the admin UI.

If you specify an {id} that does not exist among the backup targets, an error response is returned containing a non-zero value in status and the error message Could not find any backup index..

Request

GET /api/admin/backup/file/{id}

Note

If {id} contains a dot (.), as fess_config.bulk, system.properties, fess.json and search_log.ndjson do, end the URL with / (for example /api/admin/backup/file/fess_config.bulk/). A path that does not end with / and whose last segment contains a dot is treated as a request for a file with an extension. It never reaches the API, and 404 Not Found is returned.

Response

A stream of the backup file. For NDJSON format, it is returned with Content-Type: application/x-ndjson; otherwise, it is returned with application/octet-stream.

Note

Log (*.ndjson) exports are subject to the index.backup.log.load.timeout constraint (default 60000 milliseconds). If the output takes a long time, the log data may be truncated partway through.

Usage Examples

Retrieve Backup Target List

curl -X GET "http://localhost:8080/api/admin/backup/files" \
     -H "Authorization: Bearer YOUR_TOKEN"

Download Configuration Index

curl -X GET "http://localhost:8080/api/admin/backup/file/fess_config.bulk/" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -o fess_config.bulk

Download Search Log

curl -X GET "http://localhost:8080/api/admin/backup/file/search_log.ndjson/" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -o search_log.ndjson

Reference