Skip to content

Instantly share code, notes, and snippets.

@krishnasrinivas

krishnasrinivas/madmin-rest.md

Forked from krisis/madmin-rest.md
Last active December 13, 2023 21:52
Show Gist options
  • Save krishnasrinivas/ea5603d16e6d706793332af674df83e3 to your computer and use it in GitHub Desktop.
Save krishnasrinivas/ea5603d16e6d706793332af674df83e3 to your computer and use it in GitHub Desktop.
Download ZIP
Minio Management REST API spec
Raw
madmin-rest.md

Minio Management REST API

Management APIs implement remote administrative operations over HTTP/REST. This guide is intended for SDK developers of package like madmin. If you are an enduser please take a look at mc admin CLI interface.

Authentication

  • All requests should be signed using AWS Signature Version V4

FEEDBACK: We can use simpler JSON webtoken for Auth just like how minio-browser does. Tokens are a standard way of auth for REST APIs.

  • us-east-1 should be used in signing

API Categories

  • Service

    Manage Minio server process(es)

  • Locks

    Manage namespace locks held by Minio server to protect concurrent access of object store by applications

  • Heal

    Heal buckets, objects, uploads and formatting a replaced disk

  • Config

    Get and set Minio server configuration

Common elements of Minio management API

  • Request
    • x-minio-operation request header indicates the action to be performed on the endpoint

FEEDBACK: This is not needed. Instead REST endpoint and query paramenters are enough to convey the action client needs (as explained in the FEEDBACK below)

  • Response
    • Success response is either empty or JSON encoded
    • List APIs' response is XML encoded
    • Error response is always XML encoded

FEEDBACK: Request and Response can always be in JSON for admin endpoints. Even for listing response can be in JSON as conversion from/to JSON will be simple.

FEEDBACK: Error response can be in JSON. JSON Error response fields can be compatible with S3 but I think it will be restrictive for our purpose.

Operations on Service

Service Restart

Restart Minio server process(es).

  POST /?service HTTP/1.1
  Host: https://my-minio-server.com:9000
  x-minio-operation: restart
  Date: date
  Authorization: authorization string (AWS V4)

FEEDBACK:

POST /minio/admin/service/restart

Parameters

None

Headers

Name Description Required
x-minio-operation Set to restart to indicate that Minio server process(es) should be restarted Yes

Response

Status: 200 OK
Body: None

Service Status

Get status of Minio server

 GET /?service HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: status
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

GET /minio/admin/service/status

Parameters

None

Headers

Name Description Required
x-minio-operation Set to status to fetch status of Minio server process(es) Yes

Response

Status: 200 OK
Body:
   {
      "status": "success",
      "service": true,
      "uptime": 121369476533489
   }

Operations on Namespace Locks

List Locks

List namespace locks held on a bucket, prefix and held for longer than a given duration.

 GET /?lock HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: list
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

GET /minio/admin/locks?bucket=testbucket&prefix=testPrefix&older-than=1231141

Parameters

Name Description Required
bucket Name of the bucket Yes
prefix Name of the prefix No
older-than Filters locks held for longer than given time No

Headers

Name Description Required
x-minio-operation Set to list Yes

Response

Status: 200
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

Clear namespace locks held on a given bucket, prefix and held for longer than a given duration. It returns the list of locks that were cleared.

 POST /?lock HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: clear
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

DELETE /minio/admin/locks?bucket=testbucket&prefix=testPrefix&older-than=1231141

Parameters

Name Description Required
bucket Name of the bucket Yes
prefix Name of the prefix No
older-than Filters locks held for longer than given time No

Headers

Name Description Required
x-minio-operation Set to clear Yes

Response

Status: 200
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 Operations

FEEDBACK:

POST /minio/admin/heal?bucket=[BUCKET]&prefix=[PREFIX]&remove=true&recursive=true&advanced=true&fake=true&multipart=true

Heal Storage Format

Heal storage format of unformatted or corrupted disks in a Minio server. This is useful when a disk is replaced.

 POST /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: format
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

POST /minio/admin/heal

Parameters

Name Description Required
dry-run If dry-run is set the operation is not peformed No

Headers

Name Description Required
x-minio-operation Set to format Yes

Response

Status: 200
Body: None

Heal Bucket

Heals the given bucket if present.

 POST /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: bucket
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK: (heal things like policy.json)

POST /minio/admin/heal?bucket=testbucket

Parameters

Name Description Required
bucket Name of the bucket Yes
dry-run If dry-run is set the operation is not peformed No

Headers

Name Description Required
x-minio-operation Set to bucket Yes

Response

Status: 200
Body: None

Heal Object

Heal a given object.

 POST /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: object
 Date: date
 Authorization: authorization string (AWS V4)

POST /minio/admin/heal?bucket=testbucket&object=testobject

Parameters

Name Description Required
bucket Name of the bucket Yes
object Name of the object Yes
dry-run If dry-run is set the operation is not peformed No

Headers

Name Description Required
x-minio-operation Set to object Yes

Response

Status: 200
Body:
{
  "HealedCount": 1,
  "OfflineCount": 0
}

Heal Upload

Heal an incomplete multipart upload given its uploadID.

 POST /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: upload
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK: (there is no upload-id, it heals all the upload-ids for the object to keep the api simple)

POST /minio/admin/heal?bucket=testbucket&object=testobject&advanced=true&multipart=true

Parameters

Name Description Required
bucket Name of the bucket Yes
object Name of the object Yes
uploadID UploadID of upload Yes
dry-run If dry-run is set the operation is not peformed No

Headers

Name Description Required
x-minio-operation Set to upload Yes

Response

Status: 200
Body:
{
  "HealedCount": 1,
  "OfflineCount": 0
}

List Buckets Heal

Lists buckets that require healing.

FEEDBACK: this is fake=true hence separate API is not needed

 GET /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: list-buckets
 Date: date
 Authorization: authorization string (AWS V4)

Parameters

None

Headers

Name Description Required
x-minio-operation Set to list-buckets Yes

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <Owner>
    <ID>bcaf1ffd86f461ca5fb16fd081034f</ID>
    <DisplayName>webfile</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>quotes</Name>
      <CreationDate>2006-02-03T16:45:09.000Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>samples</Name>
      <CreationDate>2006-02-03T16:41:58.000Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

List Objects Heal

List objects that require healing.

FEEDBACK: this is same as fake=true and hence separate API is not needed.

 GET /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: list-objects
 Date: date
 Authorization: authorization string (AWS V4)

Parameters

Name Description Required
bucket Name of the bucket Yes
prefix Name of the prefix No
marker Specifies the key to start with when listing objects in a bucket No
delimiter Character used to group keys No
max-keys Maximum number of keys returned in the response (Default: 1000) No

Headers

Name Description Required
x-minio-operation Set to list-objects Yes

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>bucket</Name>
    <Prefix/>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>&quot;fba9dede5f27731c9771645a39863328&quot;</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>mtd@amazon.com</DisplayName>
        </Owner>
    </Contents>
    <Contents>
       <Key>my-third-image.jpg</Key>
         <LastModified>2009-10-12T17:50:30.000Z</LastModified>
         <ETag>&quot;1b2cf535f27731c974343645a3985328&quot;</ETag>
         <Size>64994</Size>
         <StorageClass>STANDARD_IA</StorageClass>
         <Owner>
            <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>mtd@amazon.com</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

List Uploads Heal

List incomplete multipart uploads that require healing.

FEEDBACK: same as when used with fake=true

 GET /?heal HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: list-uploads
 Date: date
 Authorization: authorization string (AWS V4)

Parameters

Name Description Required
bucket Name of the bucket Yes
prefix Name of the prefix No
key-marker Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin. No
upload-id-marker Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored. No
delimiter Character used to group keys No
max-uploads Maximum number of multipart uploads returned in the response (Default: 1000) No

Headers

Name Description Required
x-minio-operation Set to list-uploads Yes

Response

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>example-bucket</Bucket>
  <KeyMarker/>
  <UploadIdMarker/>
  <NextKeyMarker/>
  <NextUploadIdMarker/>
  <Delimiter>/</Delimiter>
  <Prefix>photos/2006/</Prefix>
  <MaxUploads>1000</MaxUploads>
  <IsTruncated>false</IsTruncated>
  <CommonPrefixes>
    <Prefix>photos/2006/February/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>photos/2006/January/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>photos/2006/March/</Prefix>
  </CommonPrefixes>
</ListMultipartUploadsResult>

Operations on Config

Get Config

Get Minio server configuration.

 GET /?config HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: get
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

GET /minio/admin/config

Parameters

None

Headers

Name Description Required
x-minio-operation Set to get Yes

Reponse

Status: 200 OK
Body:
{
  "version": "18",
  "credential": {
    "accessKey": "Q3AM3UQ867SPQQA43P2F",
    "secretKey": "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"
  },
  "region": "us-east-1",
... 
"browser": "on",
 "logger": {
   "console": {
     "enable": true
   },
   "file": {
     "enable": true,
     "filename": "/home/ubuntu/server.log"
   }
 },
 "notify": {
   "amqp": {
     "1": {
       "enable": false,
       "url": "",
       "exchange": "",
       "routingKey": "",
       "exchangeType": "",
       "deliveryMode": 0,
       "mandatory": false,
       "immediate": false,
       "durable": false,
       "internal": false,
       "noWait": false,
       "autoDeleted": false
     }
   },
   "nats": {
     "1": {
       "enable": false,
       "address": "",
       "subject": "",
       "username": "",
       "password": "",
       "token": "",
       "secure": false,
       "pingInterval": 0,
       "streaming": {
         "enable": false,
         "clusterID": "",
         "clientID": "",
         "async": false,
         "maxPubAcksInflight": 0
       }
     }
   },
   "elasticsearch": {
     "1": {
       "enable": false,
       "format": "namespace",
       "url": "",
       "index": ""
     }
   },
   "redis": {
     "1": {
       "enable": false,
       "format": "namespace",
       "address": "",
       "password": "",
       "key": ""
     }
   },
   "postgresql": {
     "1": {
       "enable": false,
       "format": "namespace",
       "connectionString": "",
       "table": "",
       "host": "",
       "port": "",
       "user": "",
       "password": "",
       "database": ""
     }
   },
   "kafka": {
     "1": {
       "enable": false,
       "brokers": null,
       "topic": ""
     }
   },
   "webhook": {
     "1": {
       "enable": false,
       "endpoint": ""
     }
   },
   "mysql": {
     "1": {
       "enable": false,
       "format": "namespace",
       "dsnString": "",
       "table": "",
       "host": "",
       "port": "",
       "user": "",
       "password": "",
       "database": ""
     }
   }
 }
}

Set Config

Update Minio server configuration.

 GET /?config HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: set
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

POST /mino/admin/config

Parameters

None

Headers

Name Description Required
x-minio-operation Set to set Yes

Response

Status: 200 OK
Body:
{
  "status": "success",
  "nodesSummary": [
    {
      "name": ":9000",
      "errSet": false,
      "errMsg": "<nil>"
    }
  ]
}

Set Credentials

Update credentials on Minio server.

 POST /?service HTTP/1.1
 Host: https://my-minio-server.com:9000
 x-minio-operation: creds
 Date: date
 Authorization: authorization string (AWS V4)

FEEDBACK:

POST /minio/admin/config/auth

Parameters

None

Headers

Name Description Required
x-minio-operation Set to creds to update credentials Yes

Request

<setCredsReq>
   <username>minio</username>
   <password>minio123</password>
</setCredsReq>

Response

Status: 200 OK
Body: None
@harshavardhana
Copy link

This is an old API for more recent API please refer https://github.com/minio/minio/tree/master/pkg/madmin

@MrArabboy
Copy link

This is an old API for more recent API please refer https://github.com/minio/minio/tree/master/pkg/madmin

this link raise 404

@harshavardhana
Copy link

this link raise 404

new link godoc.org/github.com/minio/madmin-go

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment