This document contains the REST API specification for version 1 of the Administration API provided by the Minio server.
- 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 toapplication/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.
This API reveals the version of the Admin API supported on the server.
- Request:
GET /minio/admin/version
- Response body:
{
"version": "1"
}
- Request:
GET /minio/admin/v1/service
- Response body:
{
"serverVersion": "xxx",
"uptime": "uptime-string"
}
- 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
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
}
}
}
]
- 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 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"
}
]
}
]
- 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.
- 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.
- 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 |
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 |
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.
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
}
]
}
For this you can use
GET
HTTP Verb like: (i.e there is no need forheal-status
in/minio/admin/v1/heal-status/...
, you can use/minio/admin/v1/heal/...
AB also wanted an
advanced
mode which does bitrot check as well.Update server configuration
andUpdate server credentials
have same endpointis
ackIndex
related toresultID
of the response?