admin-api.org

Admin API Version 1 Specification (WIP)

This document contains the REST API specification for version 1 of the Administration API provided by the Minio server.

Common Conventions

• All response bodies when present are JSON encoded (regardless of whether the request was successful or not). When present, the Content-Type header will be set in the request or response to application/json.
• All successful requests have a HTTP 200 status code in the response and are not explicitly specified below.
• All requests that may change state on the server use the POST/DELETE HTTP verb, and others use the GET HTTP verb.
• Authentication is performed per-request with the S3v4 standard.

Version API

This API reveals the version of the Admin API supported on the server.

• Request:

GET /minio/admin/version

• Response body:

{
    "version": "1"
}

Service API

Status

• Request:

GET /minio/admin/v1/service

• Response body:

{
    "serverVersion": "xxx",
    "uptime": "uptime-string"
}

Restarting and Stopping actions

• Request:

POST /minio/admin/v1/service

• Request Body:

{
    "action": "<action-value>"
}

• Request Parameters:

Purpose	Parameter Name	Parameter Value
Restart the server	action	restart
Stop the server	action	stop

• Response Body:

No response body

Info API

Provides detailed information about Minio server or server cluster.

• Request:

GET /minio/admin/v1/info

• Response Body:

The response body consists of a JSON array, with one entry per Minio server. When deployed in distributed mode, the array will contain multiple entries.

In the example shown below there is only one server (for brevity and clarity):

[
  {
    "error": "",
    "addr": "localhost:9000",
    "data": {
      "storage": {
        "Total": 485060165632,
        "Free": 19782328320,
        "Backend": {
          "Type": 2,
          "OnlineDisks": 4,
          "OfflineDisks": 0,
          "ReadQuorum": 2,
          "WriteQuorum": 3
        }
      },
      "network": {
        "transferred": 57661230,
        "received": 30322938
      },
      "http": {
        "totalHEADs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "successHEADs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "totalGETs": {
          "count": 2,
          "avgDuration": "0s"
        },
        "successGETs": {
          "count": 2,
          "avgDuration": "0s"
        },
        "totalPUTs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "successPUTs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "totalPOSTs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "successPOSTs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "totalDELETEs": {
          "count": 0,
          "avgDuration": "0s"
        },
        "successDELETEs": {
          "count": 0,
          "avgDuration": "0s"
        }
      },
      "server": {
        "uptime": 68581707868819,
        "version": "2017-08-02T19:26:47Z",
        "commitID": "2bc72cec4b88924e57381ba086de9e3b3f2dcb6b",
        "region": "us-east-1",
        "sqsARN": null
      }
    }
  }
]

Locks API

List Locks

• Request:

GET /minio/admin/v1/locks

• Request Parameters:

Purpose	Parameter Name	Parameter Type	Required
Specify bucket name	bucket	string	Yes
Specify object prefix	prefix	string	No
Specify lock age filter	older-than	duration string (like 1s, 5m, 2h)	No

• Response Body:

Response is a JSON array, with one array item per lock.

[
  {
    "bucket": "bucket",
    "object": "file",
    "readLocks": 0,
    "writeLocks": 0,
    "lockOwners": [
      {
        "id": "JHS8ZXMCFLTT6I05",
        "source": "[object-handlers.go:497:objectAPIHandlers.PutObjectHandler()]",
        "type": "WLock",
        "status": "Running",
        "since": "2017-08-03T15:23:51.272920825Z"
      }
    ]
  }
]

Clear Locks

Clear locks forcibly removes locks mactching the given parameters.

• Request:

DELETE /minio/admin/v1/locks

• Request Parameters:

Purpose	Parameter Name	Parameter Type	Required?
Specify bucket name	bucket	string	Yes
Specify object prefix	prefix	string	No
Specify lock age filter	older-than	duration string (like 1s, 5m, 2h)	No

• Response body:

Response is a JSON array, with one array item per lock matched and cleared. It is the same format as for listing locks.

[
  {
    "bucket": "bucket",
    "object": "file",
    "readLocks": 0,
    "writeLocks": 0,
    "lockOwners": [
      {
        "id": "JHS8ZXMCFLTT6I05",
        "source": "[object-handlers.go:497:objectAPIHandlers.PutObjectHandler()]",
        "type": "WLock",
        "status": "Running",
        "since": "2017-08-03T15:23:51.272920825Z"
      }
    ]
  }
]

Configuration API

Fetch server configuration

• Request:

GET /minio/admin/v1/config

• Response Body:

The response body is the same as the content of the config.json file for the server and is not shown here.

Update server configuration

• Request:

PUT /minio/admin/v1/config

• Request Body:

The request body is the same as the content of the config.json file for the server and is not shown here. This JSON content will become the new configuration of the server.

Update server credentials

• Request:

PUT /minio/admin/v1/config/credential

• Request Parameters:

Purpose	Parameter Name	Parameter Type	Required?
Specify the access key	accessKey	string	Yes
Specify the secret key	secretKey	string	Yes

Heal API

The Heal API is provided as a single POST endpoint. It is used to both start a heal sequence and to fetch the results of a heal sequence.

Only one heal sequence may run under a particular heal path and no other heal sequence may run on an overlapping path as well.

• Request:

The path of items to be healed is specified in the URL path. We may specify either that:

• all buckets must be healed, or
• a particular bucket must be healed, or
• a particular bucket with objects under a certain prefix,

must be healed.

Each of the above correspond to each line of the example below:

POST /minio/admin/v1/heal/
POST /minio/admin/v1/heal/<bucket-name>
POST /minio/admin/v1/heal/<bucket-name>/<object-prefix>

• Request Body:

The request body contains heal settings in a JSON object. These add further specifications for items to be healed.

Purpose	Parameter Name
Enable recursive traversal of given path to heal	recursive
Disable mutation of data during healing	dryRun
Also heal incomplete uploads	incomplete

• Request Parameters:

Certain operational or book-keeping URL (or query) parameters are accepted by the Heal API, specified below:

Purpose	Parameter Name
To force a (re)start a Heal sequence	forceStart
To fetch heal sequence results using unique token	clientToken

Starting a heal sequence

To start a heal sequence use the above specified request structure, body and parameters, but do not specify a `clientToken`. The server responds with a client token that will be unique:

{
  "clientToken": "3536a193-c1bd-44e3-85fc-20bfb5a1a4e5",
  "clientAddress": "172.19.0.1:58106",
  "startTime": "2018-01-04T01:30:02.114052901Z"
}

This token can be used to heal results for this heal sequence (see next section).

If a heal process is already running on the same path, an error is returned. To force start the heal sequence the `forceStart` parameter needs to be supplied (with any value). This will cause the existing heal sequence to be stopped and a new one to be started in its place.

Fetch results of a heal sequence

Heal result records may be fetched for a previously started heal sequence by specifying the `clientToken` parameter with the value received when starting the heal sequence.

The server returns heal result records in the order they are generated on the server. An example follows:

{
    "Summary": "finished",
    "StartTime": "2018-01-04T01:42:47.775896212Z",
    "NumDisks": 4,
    "Settings": {
        "recursive": true,
        "dryRun": false,
        "incomplete": false
    },
    "Items": [
        {
            "resultId": 1,
            "type": "metadata",
            "bucket": "",
            "object": "",
            "detail": "disk-format",
            "diskCount": 4,
            "drives": {
                "before": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                },
                "after": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                }
            },
            "objectSize": 0
        },
        {
            "resultId": 2,
            "type": "bucket",
            "bucket": "somedata",
            "object": "",
            "detail": "",
            "diskCount": 4,
            "drives": {
                "before": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                },
                "after": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                }
            },
            "objectSize": 0
        },
        {
            "resultId": 3,
            "type": "object",
            "bucket": "somedata",
            "object": "2017-07-16-205749.webm",
            "detail": "",
            "parityBlocks": 2,
            "dataBlocks": 2,
            "diskCount": 4,
            "drives": {
                "before": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                },
                "after": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                }
            },
            "objectSize": 6035320
        },
        {
            "resultId": 4,
            "type": "object",
            "bucket": "somedata",
            "object": "2017-07-16-205832.webm",
            "detail": "",
            "parityBlocks": 2,
            "dataBlocks": 2,
            "diskCount": 4,
            "drives": {
                "before": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                },
                "after": {
                    "http://minio1:9000/export": "ok",
                    "http://minio2:9000/export": "ok",
                    "http://minio3:9000/export": "ok",
                    "http://minio4:9000/export": "ok"
                }
            },
            "objectSize": 3176694
        }
    ]
}

Fetch status of a heal seqeuence

Request:
There are 3 variations similar to the two previous Heal APIs. The path provided, identifies the specific heal sequence for fetching status.

POST /minio/admin/v1/heal-status/
POST /minio/admin/v1/heal-status/<bucket-name>
POST /minio/admin/v1/heal-status/<bucket-name>/<object-prefix>

For this you can use GET HTTP Verb like: (i.e there is no need for heal-status in /minio/admin/v1/heal-status/..., you can use /minio/admin/v1/heal/...

GET /minio/admin/v1/heal/
GET /minio/admin/v1/heal/<bucket-name>
GET /minio/admin/v1/heal/<bucket-name>/<object-prefix>

AB also wanted an advanced mode which does bitrot check as well.

Update server configuration and Update server credentials have same endpoint

is ackIndex related to resultID of the response?