Configuring for the RESTful API

The RapidDisk RESTful API is exposed through the rapiddiskd daemon. The default port is 9118, however, you can specify the port during execution. Please ensure that the port is open for TCP within your firewall rules. You can also start this daemon manually or via systemd:

After installation, to start the service via systemd:

$ sudo systemctl start rapiddiskd.service

To check the status of the service via systemd:

$ sudo systemctl status rapiddiskd.service

To stop the service via systemd:

$ sudo systemctl stop rapiddiskd.service

To start the service at boot via systemd:

$ sudo systemctl enable rapiddiskd.service

The API

GET /v1/checkServiceStatus

ex) curl -s --output - 127.0.0.1:9118/v1/checkServiceStatus|jq .

status code: 200 (on success)

Check the status of the daemon. Example output:

{ 
  "status": "OK",
  "version": "7.0.0"
}

GET /v1/listAllResources

ex) curl -s --output - 127.0.0.1:9118/v1/listAllResources|jq .

status code: 200 (on success)

Retrieve system resource information. Example output:

{ 
  "resources": [
    { 
      "memory": [
        { 
          "mem_total": 2084130816,
          "mem_free": 229003264
        }
      ]
    },
    { 
      "volumes": [
        { 
          "device": "sda",
          "size": 26843545600,
          "vendor": "ATA",
          "model": "VBOX"
        }
      ]
    }
  ]
}

GET /v1/listRapidDiskVolumes

ex) curl -s --output - 127.0.0.1:9118/v1/listRapidDiskVolumes|jq .

status code: 200 (on success)

Retrieve rapiddisk/cache information. Example output:

{ 
  "volumes": [
    { 
      "rapiddisk": [
        { 
          "device": "rd1",
          "size": 67108864,
          "usage": 4096,
          "status": "locked"
        },
        {
          "device": "rd0",
          "size": 67108864,
          "usage": 65536,
          "status": "unlocked"
        }
      ]
    },
    {
      "rapiddisk_cache": [
        {
          "device": "rc-wa_loop7",
          "cache": "rd0",
          "source": "loop7",
          "mode": "write-around"
        }
      ]
    }
  ]
}

POST /v1/createRapidDisk/@size

ex) curl -X POST -s 127.0.0.1:9118/v1/createRapidDisk/128|jq .

status code: 200 (on success)

Create a rapiddisk volume. Example output:

{
  "status": "Success"
}

POST /v1/resizeRapidDisk/@volume/@size

ex) curl -X POST -s 127.0.0.1:9118/v1/resizeRapidDisk/rd0/128|jq .

status code: 200 (on success)

Resize an existing rapiddisk volume. Example output:

{
  "status": "Success"
}

POST /v1/flushRapidDisk/@volume

ex) curl -X POST -s 127.0.0.1:9118/v1/flushRapidDisk/rd0|jq .

status code: 200 (on success)

Flush the memory of an existing rapiddisk volume. Example output:

{
  "status": "Success"
}

POST /v1/removeRapidDisk/@volume

ex) curl -X POST -s 127.0.0.1:9118/v1/removeRapidDisk/rd0|jq .

status code: 200 (on success)

Remove an existing rapiddisk volume. Example output:

{
  "status": "Success"
}

POST /v1/createRapidDiskCache/@volume/@source/@policy

ex) curl -X POST -s 127.0.0.1:9118/v1/createRapidDiskCache/rd0/sdb/write-through|jq .

Supported caching policies:

• write-through
• write-around

status code: 200 (on success)

Create a rapiddisk-cache volume. Example output:

{
  "status": "Success"
}

POST /v1/removeRapidDiskCache/@volume

ex) curl -X POST -s 127.0.0.1:9118/v1/removeRapidDiskCache/rc-wt_sdb|jq .

status code: 200 (on success)

Remove an existing rapiddisk-cache volume. Example output:

{
  "status": "Success"
}

GET /v1/showRapidDiskCacheStats/@volume

ex) curl -s --output - 127.0.0.1:9118/v1/showRapidDiskCacheStats/rc-wt_sdb|jq .

status code: 200 (on success)

Retrieve cache statistics from an existing rapiddisk-cache volume. Example output:

{
  "statistics": [
    {
      "cache_stats": [
        {
          "device": "rc-wt_loop7",
          "reads": 527,
          "writes": 1,
          "cache_hits": 264,
          "replacement": 0,
          "write_replacement": 0,
          "read_invalidates": 1,
          "write_invalidates": 1,
          "uncached_reads": 1,
          "uncached_writes": 0,
          "disk_reads": 263,
          "disk_writes": 1,
          "cache_reads": 264,
          "cache_writes": 263
        }
      ]
    }
  ]
}

If it is writeback cache, it will look like this:

{
  "statistics": [
    {
      "cache_stats": [
        {
          "device": "rc-wb_sdd",
          "errors": 0,
          "num_blocks": 16320,
          "num_free_blocks": 16320,
          "num_wb_blocks": 0
        }
      ]
    }
  ]
}

POST /v1/lockRapidDisk/@volume

ex) curl -X POST -s 10.0.0.185:9118/v1/lockRapidDisk/rd0|jq .

status code: 200 (on success)

Lock an existing rapiddisk volume (set to read-only). Example output:

{ "status": "Success" }

POST /v1/unlockRapidDisk/@volume

ex) curl -X POST -s 10.0.0.185:9118/v1/unlockRapidDisk/rd0|jq .

status code: 200 (on success)

Lock an existing rapiddisk volume (set to read-write). Example output:

{ "status": "Success" }

GET /v1/listAllNVMeTargets

ex) curl -s --output - 10.0.0.185:9118/v1/listAllNVMeTargets|jq .

status code: 200 (on success)

Retrieve cache statistics from an existing rapiddisk-cache volume. Example output:

{
  "targets": [
    {
      "nvmet_targets": [
        {
          "nqn": "rd1-test",
          "namespace": 2,
          "device": "/dev/rd2",
          "enabled": "true"
        },
        {
          "nqn": "rd1-test",
          "namespace": 1,
          "device": "/dev/rd1",
          "enabled": "true"
        }
      ]
    },
    {
      "nvmet_ports": [
        {
          "port": 1,
          "address": "10.0.0.185",
          "protocol": "tcp",
          "nqn": "rd1-test"
        }
      ]
    }
  ]
}

GET /v1/listAllNVMePorts

ex) curl -s --output - 10.0.0.185:9118/v1/listAllNVMePorts|jq .

status code: 200 (on success)

Retrieve cache statistics from an existing rapiddisk-cache volume. Example output:

{
  "targets": [
    {
      "nvmet_ports": [
        {
          "port": 1,
          "address": "10.0.0.185",
          "protocol": "tcp"
        }
      ]
    }
  ]
}