Home Original page

kvrocks-controller/docs/API.md at unstable · apache/kvrocks-controller

HTTP APIs

Namespace APIs

Create Namespace

Request Body

{
  "namespace": "test-ns"
}

Response JSON Body

  • 201
  • 409
{
  "error": {
    "message": "the entry already existed"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

List Namespace

Response JSON Body

  • 200
{
  "data": {
    "namespaces": ["test-ns"]
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Delete Namespace

GET /api/v1/namespaces/{namespace}

Response JSON Body

  • 200
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Cluster APIs

Create Cluster

POST /api/v1/namespaces/{namespace}/clusters

Request Body

{
  "name":"test-cluster",
  "nodes":["127.0.0.1:6666"],
  "replicas":1,
  "password":""
}

Response JSON Body

  • 201
  • 409
{
  "error": {
    "message": "the entry already existed"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

List Cluster

GET /api/v1/namespaces/{namespace}/clusters

Response JSON Body

  • 200
{
  "data": {
    "clusters": ["test-cluster"]
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Import Cluster

This API is used to import the cluster from the existing Kvrocks cluster's nodes.

POST /api/v1/namespaces/{namespace}/clusters/{cluster}/import

Request Body

{
  "nodes":["127.0.0.1:6666"],
  "password":""
}

Response JSON Body

  • 201
  • 409
{
  "error": {
    "message": "the entry already existed"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Get Cluster

GET /api/v1/namespaces/{namespace}/clusters/{cluster}

Response JSON Body

  • 200
{
  "data":
  {
    "cluster": {
      "name":"test-cluster",
      "version":0,
      "shards":[
        {"nodes":[
          {
            "id":"YotDSqzTeHK6CnIX2gZu27IlcYRTW4dkkFQvV382",
            "addr":"127.0.0.1:6666",
            "role":"master",
            "password":"",
            "master_auth":"",
            "created_at":16834433980
          }],
          "slot_ranges":["0-16383"],
          "import_slot":-1,
          "migrating_slot":-1
        }
      ]
    }
  }
}
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Delete Cluster

DELETE /api/v1/namespaces/{namespace}/clusters/{cluster}

Response JSON Body

  • 200
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Shard APIs

Create Shard

POST /api/v1/namespaces/{namespace}/clusters/{cluster}/shards

Request Body

{
  "nodes":["127.0.0.1:6666"],
  "password":""
}

Response JSON Body

  • 201
  • 409
{
  "error": {
    "message": "the entry already existed"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Get Shard

GET /api/v1/namespaces/{namespace}/clusters/{cluster}/shards/{shard}

Response JSON Body

  • 200
{
  "data": {
    "shard": {
      "nodes": [
        {
          "id": "3SStZULMqclwvYNT8gN05IdybROe0vEnn97iNB5Z",
          "addr": "127.0.0.1:6666",
          "role": "master",
          "password": "",
          "master_auth": "",
          "created_at": 16834433980
        }
      ],
      "slot_ranges": [
        "0-16383"
      ],
      "import_slot": -1,
      "migrating_slot": -1
    }
  }
}
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

List Shard

GET /api/v1/namespaces/{namespace}/clusters/{cluster}/shards

Response JSON Body

  • 200
{
  "data": {
    "shards": [
      {
        "nodes": [
          {
            "id": "3SStZULMqclwvYNT8gN05IdybROe0vEnn97iNB5Z",
            "addr": "127.0.0.1:6666",
            "role": "master",
            "password": "",
            "master_auth": "",
            "created_at": 16834433980
          }
        ],
        "slot_ranges": [
          "0-16383"
        ],
        "import_slot": -1,
        "migrating_slot": -1
      },
      {
        "nodes": [
          {
            "id": "y5PftTd0Lc3hH34yEyavIji86cRM5i3oxytt42vo",
            "addr": "127.0.0.1:6667",
            "role": "master",
            "password": "",
            "master_auth": "",
            "created_at": 16834433980
          }
        ],
        "slot_ranges": null,
        "import_slot": -1,
        "migrating_slot": -1
      }
    ]
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Delete Shard

DELETE /api/v1/namespaces/{namespace}/clusters/{cluster}/shards/{shard}

Response JSON Body

  • 200
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Failover master node in a shard

POST /api/v1/namespaces/{namespace}/clusters/{cluster}/shards/{shard}/failover

Request Body

{
  "preferred_node_id": "{YOUR PREFERRED NODE ID}"
}

Response JSON Body

  • 200
{
  "data": {
    "new_master_id": "{NEW MASTER ID}"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Node APIs

Create Node

POST /api/v1/namespaces/{namespace}/clusters/{cluster}/shards/{shard}/nodes

Request Body

{
  "addr": "127.0.0.1:6666",
  "role": "slave",
  "password":""
}

Response JSON Body

  • 201
  • 409
{
  "error": {
    "message": "the entry already existed"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

List Node

GET /api/v1/namespaces/{namespace}/clusters/{cluster}/shards/{shard}/nodes

Response JSON Body

  • 200
{
  "data": {
    "nodes": [
      {
        "id": "pxpE1JSBJcqicuwc95zqTPTj5rB7YtfvpociyH8C",
        "addr": "127.0.0.1:6666",
        "role": "master",
        "password": "",
        "created_at": 1686101693
      },
      {
        "id": "O0JKq1Hp9FtI3dJTU3MigWjjZJzPtduoDODX0OAY",
        "addr": "127.0.0.1:6667",
        "role": "slave",
        "password": "",
        "created_at": 1686102057
      }
    ]
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Delete Node

DELETE /api/v1/namespaces/{namespace}/clusters/{cluster}/shards/{shard}/nodes/{nodeID}

Response JSON Body

  • 200
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}

Migration APIs

Migrate Slot

POST /api/v1/namespaces/{namespace}/clusters/{cluster}/migrate

Request Body

{
  "target": 1,
  "slot": 123,
  "slot_only": "false" 
}

Response JSON Body

  • 200
  • 404
{
  "error": {
    "message": "the entry does not exist"
  }
}
  • 5XX
{
  "error": {
    "message": "DETAIL ERROR STRING"
  }
}