Skip to content

Instantly share code, notes, and snippets.

@krisis

krisis/madmin-rest.md

Last active March 5, 2023 19:25
Show Gist options
  • Save krisis/3a92e3d7f204cdb2be4355fc01f0759a to your computer and use it in GitHub Desktop.
Save krisis/3a92e3d7f204cdb2be4355fc01f0759a 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
  • 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

  • Response

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

  • Error Responses

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)

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)

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)

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)

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

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)

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)

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)

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)

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.

 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.

 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.

 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)

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)

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)

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
@donatello
Copy link

APIs' response bodies are inconsistently in JSON and XML. Only one response format is supported (currently) and some requests use XML, most use JSON and all errors use XML.

A more appropriate way is to use the Content-Header value provided by the client and use that to change the response format accordingly - e.g.:
application/json -> server returns JSON in the response, or
application/xml -> server returns XML in the response.

By default, we could use any one of JSON or XML for all requests (probably XML since S3 uses that exclusively).

These changes would make the APIs consistent and pleasant to write SDKs for - they could stick with one of either a JSON or an XML library.

@deekoder
Copy link

deekoder commented Apr 11, 2017 •
edited

I was wondering the same on JSON/XML. As an application dev, i always think JSON is easier for me to understand a sample response in documentation. But that might be just me.

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