krishnasrinivas/admin-api.md

## admin-api.md

      
    Raw
  

              admin-api.md
            
          
    Took inspirtion from DigitalOcean REST APIs: https://developers.digitalocean.com/documentation/v2/
Convention:


Use GET, POST, DELETE http verbs. No case for PUT.
Use JSON request/responses.
Auth happens using S3V4
if a boolean query paramenter is passed without value then the value is assumed to be true. For ex ?recursive is same as ?recursive=true

API Categories

Version, Service, Locks, Heal, Config
Version

(Note that the request endpoint is not /minio/admin/v1/version)
Request: GET /minio/admin/version
Response Body:
{
   version: "1"
}

Client can use this endpoint to figure what REST API version the server is running so that it can use appropriate madmin version.
Service


Restart

Request: POST /minio/admin/v1/service
Request Body:
{
   action: restart
}

Response Body: EMPTY
Stop

Restart

Request: POST /minio/admin/v1/service
Request Body: EMPTY
{
   action: stop
}

Response Body: EMPTY
Status

Request : GET /minio/admin/v1/service
Request Body: EMPTY
Response Body:
   {
      "status": "stop",
      "service": true,
      "uptime": 121369476533489
   }

Locks


List locks

Request : GET /minio/admin/v1/locks?bucket=my-bucket&prefix=my-prefix&older-than=1231141
older-than is in seconds
Request Body: EMPTY
Response Body:
{
  "bucket": "my-bucket",
  "object": "my-prefix",
  "readLocks": 0,
  "writeLocks": 1,
  "lockOwners": [
    {
      "id": "5236849b-9ef5-4258-93aa-6b6d7c57dcf1",
      "source": "[web-handlers.go:284:(*webAPIHandlers).RemoveObject.func1()] LockType:WLock Status:Blocked Since:2017-03-22 04:40:37.031610943 +0000 UTC Duration:63h58m31.901491283s}",
      "type": "WLock",
      "status": "Blocked",
      "since": "2017-03-22 04:25:43.415475148 +0000 UTC",
      "duration": 64h13m25.517627078s
    }
  ]
}

Clear locks

Request: DELETE /minio/admin/v1/locks?bucket=my-bucket&prefix=my-prefix&older-than=1231141
older-than is in seconds
Request Body: EMPTY
Response Body:
{
  "bucket": "my-bucket",
  "object": "my-prefix",
  "readLocks": 0,
  "writeLocks": 1,
  "lockOwners": [
    {
      "id": "5236849b-9ef5-4258-93aa-6b6d7c57dcf1",
      "source": "[web-handlers.go:284:(*webAPIHandlers).RemoveObject.func1()] LockType:WLock Status:Blocked Since:2017-03-22 04:40:37.031610943 +0000 UTC Duration:63h58m31.901491283s}",
      "type": "WLock",
      "status": "Blocked",
      "since": "2017-03-22 04:25:43.415475148 +0000 UTC",
      "duration": 64h13m25.517627078s
    }
  ]
}

Heal

Heal initiate

Request: POST /minio/admin/v1/heal
Request body:
{
path: "testbucket/a/b"
recursive: true,
advanced: true,
fake: true,
healMultipart: true,
remove: true
}
Description:

path: bucket + prefix path
recursive: heal recursively
advanced: check bit rot
fake: dry run
healMultipart: heal uncommitted objects
remove: remove objects that can not be recovered

Response Body:
{
  healTaskID: "testbucket/a/b"
}

More detailed explanation: https://gist.github.com/krishnasrinivas/615eb3d1428c7eb5a8c7fa059ed199a2
Heal status

Request: GET /minio/admin/v1/heal/healTaskID
Example: GET /minio/admin/v1/heal/testbucket/a/b
Response Body:
{
  status: "running",
  objects: [
    {type: "minioMeta", metaFile: "format.json", disks: [1,2,3,4,5,6,7,8]},
    {type: "bucket", bucketName: "testbucket", disks: [1,2,3,4,5,6,7,8]},
    {type: "object", bucketName: "testbucket", objectName: "objectname1", disks: [1,2,4,6,7,8],
    {type: "object", bucketName: "testbucket", objectName: "objectname2", disks: [1,2,4,6,7,8],
    {type: "object", bucketName: "testbucket", objectName: "objectname3", disks: [1,2,4,6,7,8],
    {type: "multipart", bucketName: "testbucket", objectName: "objectname4", disks: [1,2,4,6,7,8],
    {type: "multipart", bucketName: "testbucket", objectName: "objectname5", disks: [1,2,4,6,7,8],
  ]
}

The list of objects healed is kept in a circular linked list of fixed length (FIFO).
After the heal task completes, the status will be "completed" and some information is kept in memory till a timeout so that clients can query the state of the heal task.
Heal Terminate

DELETE /minio/admin/v1/heal/healTaskID
Example: DELETE /minio/admin/v1/heal/testbucket/a/b
If the heal task is running then it will terminate it. If the heal task is completed then its reference is removed from the memory.
Config

Get Config

Request: GET /minio/admin/v1/config
Request Body: EMPTY
Response Body:
{
    //config.json
}

Set Config

Request: POST /minio/admin/v1/config
Request body:
{
    //config.json
}

Response Body: EMPTY
Set credential

Request: POST /minio/admin/v1/config/credential
Request body:
{
    accessKey: ACCESS_KEY,
    secretKey: SECRET_KEY
}

Response Body: EMPTY