Riak Explorer API

The Riak Explorer project provides REST APIs for data viewing and cluster management for Riak clusters.

Resource Group ¶

Group Explore ¶

The /explore set of endpoints serves as an enhancement to Riak’s own HTTP API, and fills in missing data browsing and management functionality.

Explorer Ping ¶

Get Ping Result
GET`/explore/ping`

Perform an HTTP Ping, to ensure the Explorer service is up and running.

Example URI

GET http://localhost:9000/explore/ping

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "ping": {
    "id": "ping",
    "message": "pong"
  },
  "links": {
    "self": "/explore/ping"
  }
}

Clusters Collection ¶

List All Clusters
GET`/explore/clusters`

Get a list of all the clusters listed in Explorer’s riak_explorer.conf file, sorted alphabetically by cluster id.

Example URI

GET http://localhost:9000/explore/clusters

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "clusters": [
    {
      "available": false,
      "development_mode": false,
      "id": "production1",
      "riak_node": "riak@192.168.0.1",
      "riak_type": "unavailable",
      "riak_version": "unavailable"
    },
    {
      "available": false,
      "development_mode": true,
      "id": "qa1",
      "riak_node": "dev8@127.0.0.1",
      "riak_type": "unavailable",
      "riak_version": "unavailable"
    },
    {
      "available": true,
      "development_mode": true,
      "id": "localdev",
      "riak_node": "dev1@127.0.0.1",
      "riak_type": "oss",
      "riak_version": "2.1.0"
    }
  ],
  "links": {
    "self": "/explore/clusters"
  }
}

Cluster ¶

Retrieve a Cluster
GET`/explore/clusters/{cluster_id}`

Get the properties of a cluster listed in Explorer’s riak_explorer.conf file.

Example URI

GET http://localhost:9000/explore/clusters/localdev

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id as defined in the riak_explorer.conf file.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "cluster": {
    "available": true,
    "development_mode": true,
    "id": "localdev",
    "riak_node": "dev1@127.0.0.1",
    "riak_type": "oss",
    "riak_version": "2.1.0"
  },
  "links": {
    "self": "/explore/clusters/localdev"
  }
}

Response 404

HideShow

Headers

Content-Type: text/html

Nodes Collection ¶

List all Nodes
GET`/explore/clusters/nodes`

Get a list of all Nodes that are joined into the specified cluster.

Example URI

GET http://localhost:9000/explore/clusters/nodes

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "nodes": [
    {
      "id": "dev1@127.0.0.1"
    },
    {
      "id": "dev2@127.0.0.1"
    },
    {
      "id": "dev3@127.0.0.1"
    }
  ],
  "links": {
    "self": "/explore/clusters/localdev/nodes"
  }
}

Response 404

HideShow

Headers

Content-Type: text/html

Node ¶

Retrieve a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}`

Retrieves the properties of a single node within the specified cluster.

Example URI

GET http://localhost:9000/explore/clusters/localdev/nodes/dev1@127.0.0.1

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
node_id: string (required) Example: dev1@127.0.0.1
The Riak node id (in distributed Erlang node format).

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "node": {
    "id": "riak@127.0.0.1"
  },
  "links": {
    "self": "/explore/clusters/localdev/nodes/dev1@127.0.0.1"
  }
}

Response 404

HideShow

Headers

Content-Type: text/html

Node Effective Config ¶

Retrieve a Node's effective config
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/config`

Retrieves the effective config settings for a specified node (the equivalent of running riak config effective on the command line).

Note the advanced_config section. Since Riak’s advanced.config file is not parsed by cuttlefish, its settings are not included in the effective config output. Explorer includes the various settings in that file explicitly, for developer convenience, in Erlang term config format.

In some cases where a cluster was upgraded from Riak 1.4, nodes will have legacy app.config and vm.args files instead of riak.conf, and cuttlefish will not be able to provide effective config listings. In those cases, it will return a 404 Object Not Found in application/json format, with the following error body:

{
    "error": "Legacy configuration files found, effective config not available."
}

If an invalid node id is specified:

{
    "error": "Invalid node id or node not available."
}

Example URI

GET http://localhost:9000/explore/clusters/localdev/nodes/dev1@127.0.0.1/config

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
node_id: string (required) Example: dev1@127.0.0.1
The Riak node id (in distributed Erlang node format).

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "config": {
    "advanced_config": [
      "{riak_core,[{cluster_mgr,{\"127.0.0.1\",8098}}]}",
      "{riak_repl,[{data_root,\"/var/db/riak/riak_repl/\"}]}"
    ],
    "config": {
      "anti_entropy": "active",
      "anti_entropy.bloomfilter": "on",
      "anti_entropy.concurrency_limit": "2",
      "anti_entropy.data_dir": "$(platform_data_dir)/anti_entropy",
      "anti_entropy.max_open_files": "20",
      "anti_entropy.throttle": "on",
      "anti_entropy.tree.build_limit.number": "1",
      "anti_entropy.tree.build_limit.per_timespan": "1h",
      "anti_entropy.tree.expiry": "1w",
      "anti_entropy.trigger_interval": "15s",
      "anti_entropy.use_background_manager": "off",
      "anti_entropy.write_buffer_size": "4MB",
      "background_manager": "off",
      "bitcask.data_root": "$(platform_data_dir)/bitcask",
      "bitcask.expiry": "off",
      "bitcask.expiry.grace_time": "0",
      "bitcask.fold.max_age": "unlimited",
      "bitcask.fold.max_puts": "0",
      "bitcask.hintfile_checksums": "strict",
      "bitcask.io_mode": "erlang",
      "bitcask.max_file_size": "2GB",
      "bitcask.max_merge_size": "100GB",
      "bitcask.merge.policy": "always",
      "bitcask.merge.thresholds.dead_bytes": "128MB",
      "bitcask.merge.thresholds.fragmentation": "40",
      "bitcask.merge.thresholds.small_file": "10MB",
      "bitcask.merge.triggers.dead_bytes": "512MB",
      "bitcask.merge.triggers.fragmentation": "60",
      "bitcask.merge.window.end": "23",
      "bitcask.merge.window.start": "0",
      "bitcask.merge_check_interval": "3m",
      "bitcask.merge_check_jitter": "30%",
      "bitcask.open_timeout": "4s",
      "bitcask.sync.strategy": "none",
      "buckets.default.allow_mult": "false",
      "buckets.default.basic_quorum": "false",
      "buckets.default.dw": "quorum",
      "buckets.default.last_write_wins": "false",
      "buckets.default.merge_strategy": "1",
      "buckets.default.n_val": "3",
      "buckets.default.notfound_ok": "true",
      "buckets.default.pr": "0",
      "buckets.default.pw": "0",
      "buckets.default.r": "quorum",
      "buckets.default.rw": "quorum",
      "buckets.default.w": "quorum",
      "check_crl": "on",
      "datatypes.compression_level": "1",
      "distributed_cookie": "riak",
      "dtrace": "off",
      "erlang.K": "on",
      "erlang.W": "w",
      "erlang.async_threads": "64",
      "erlang.crash_dump": "./log/erl_crash.dump",
      "erlang.distribution_buffer_size": "32MB",
      "erlang.fullsweep_after": "0",
      "erlang.max_ets_tables": "256000",
      "erlang.max_ports": "65536",
      "erlang.process_limit": "256000",
      "erlang.schedulers.compaction_of_load": "false",
      "erlang.schedulers.force_wakeup_interval": "500",
      "erlang.shutdown_time": "10s",
      "erlang.smp": "enable",
      "handoff.inbound": "on",
      "handoff.ip": "127.0.0.1",
      "handoff.max_rejects": "6",
      "handoff.outbound": "on",
      "handoff.port": "10019",
      "handoff.use_background_manager": "off",
      "honor_cipher_order": "on",
      "javascript.hook_pool_size": "2",
      "javascript.map_pool_size": "8",
      "javascript.maximum_heap_size": "8MB",
      "javascript.maximum_stack_size": "16MB",
      "javascript.reduce_pool_size": "6",
      "leveldb.block.restart_interval": "16",
      "leveldb.block.size": "4KB",
      "leveldb.block.size_steps": "16",
      "leveldb.block_cache_threshold": "32MB",
      "leveldb.bloomfilter": "on",
      "leveldb.compaction.trigger.tombstone_count": "1000",
      "leveldb.compression": "on",
      "leveldb.data_root": "$(platform_data_dir)/leveldb",
      "leveldb.fadvise_willneed": "false",
      "leveldb.limited_developer_mem": "on",
      "leveldb.maximum_memory.percent": "70",
      "leveldb.sync_on_write": "off",
      "leveldb.threads": "71",
      "leveldb.tiered": "off",
      "leveldb.verify_checksums": "on",
      "leveldb.verify_compaction": "on",
      "leveldb.write_buffer_size_max": "60MB",
      "leveldb.write_buffer_size_min": "30MB",
      "listener.http.internal": "127.0.0.1:10018",
      "listener.protobuf.internal": "127.0.0.1:10017",
      "log.console": "both",
      "log.console.file": "$(platform_log_dir)/console.log",
      "log.console.level": "info",
      "log.crash": "on",
      "log.crash.file": "$(platform_log_dir)/crash.log",
      "log.crash.maximum_message_size": "64KB",
      "log.crash.rotation": "$D0",
      "log.crash.rotation.keep": "5",
      "log.crash.size": "10MB",
      "log.error.file": "$(platform_log_dir)/error.log",
      "log.error.messages_per_second": "100",
      "log.error.redirect": "on",
      "log.syslog": "off",
      "log.syslog.facility": "daemon",
      "log.syslog.ident": "riak",
      "log.syslog.level": "info",
      "max_concurrent_requests": "50000",
      "metadata_cache_size": "off",
      "nodename": "dev1@127.0.0.1",
      "object.format": "1",
      "object.siblings.maximum": "100",
      "object.siblings.warning_threshold": "25",
      "object.size.maximum": "50MB",
      "object.size.warning_threshold": "5MB",
      "platform_bin_dir": "./bin",
      "platform_data_dir": "./data",
      "platform_etc_dir": "./etc",
      "platform_lib_dir": "./lib",
      "platform_log_dir": "./log",
      "protobuf.backlog": "128",
      "protobuf.keepalive": "on",
      "protobuf.nagle": "off",
      "retry_put_coordinator_failure": "on",
      "riak_control": "off",
      "riak_control.auth.mode": "off",
      "ring.state_dir": "$(platform_data_dir)/ring",
      "ring_size": "64",
      "runtime_health.thresholds.busy_ports": "2",
      "runtime_health.thresholds.busy_processes": "30",
      "runtime_health.triggers.distribution_port": "on",
      "runtime_health.triggers.port": "on",
      "runtime_health.triggers.process.garbage_collection": "off",
      "runtime_health.triggers.process.heap_size": "160444000",
      "runtime_health.triggers.process.long_schedule": "off",
      "sasl": "off",
      "search": "off",
      "search.anti_entropy.data_dir": "$(platform_data_dir)/yz_anti_entropy",
      "search.root_dir": "$(platform_data_dir)/yz",
      "search.solr.jmx_port": "10013",
      "search.solr.jvm_options": "-d64 -Xms1g -Xmx1g -XX:+UseStringCache -XX:+UseCompressedOops",
      "search.solr.port": "10014",
      "search.solr.start_timeout": "30s",
      "secure_referer_check": "on",
      "storage_backend": "bitcask",
      "strong_consistency": "off",
      "tls_protocols.sslv3": "off",
      "tls_protocols.tlsv1": "off",
      "tls_protocols.tlsv1.1": "off",
      "tls_protocols.tlsv1.2": "on",
      "transfer_limit": "2",
      "vnode_management_timer": "10s"
    }
  },
  "links": {
    "self": "/explore/clusters/localdev/nodes/dev1@127.0.0.1/config"
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Invalid node id or node not available."
}

Node Config Files Collection ¶

List all config files for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/config/files`

Retrieves a list of all config files that reside in that node’s etc directory.

Example URI

GET http://localhost:9000/explore/clusters/localdev/nodes/dev1@127.0.0.1/config/files

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
node_id: string (required) Example: dev1@127.0.0.1
The Riak node id (in distributed Erlang node format).

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "files": [
    {
      "id": "advanced.config"
    },
    {
      "id": "riak.conf"
    },
    {
      "id": "solr-log4j.properties"
    }
  ],
  "links": {
    "self": "/explore/clusters/localdev/nodes/dev1@127.0.0.1/config/files"
  }
}

Node Config File ¶

Retrieve a Config File for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/config/files/{file_name}`

Retrieves a specific config file that belongs to a node, in its entirety.

Example URI

GET http://localhost:9000/explore/clusters/localdev/nodes/dev1@127.0.0.1/config/files/riak.conf

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
node_id: string (required) Example: dev1@127.0.0.1
The Riak node id (in distributed Erlang node format).
file_name: string (required) Example: riak.conf
Name of the config file.

Response 200

HideShow

Headers

Content-Type: plain/text
Accept: plain/text

Body

## Where to emit the default log messages (typically at 'info'
## severity):
## off: disabled
## file: the file specified by log.console.file
## console: to standard output (seen when using `riak attach-direct`)
## both: log.console.file and standard out.
##
## Default: both
##
## Acceptable values:
##   - one of: off, file, console, both
log.console = both
...

Response 404

HideShow

Headers

Content-Type: text/html

Node Log Files Collection ¶

List all Log Files for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/log/files`

Retrieves a list of all log files that reside in that node’s log directory.

Example URI

GET http://localhost:9000/explore/clusters/localdev/nodes/dev1@127.0.0.1/log/files

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
node_id: string (required) Example: dev1@127.0.0.1
The Riak node id (in distributed Erlang node format).

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "files": [
    {
      "id": "console.log"
    },
    {
      "id": "console.log.0"
    },
    {
      "id": "crash.log"
    },
    {
      "id": "erlang.log.1"
    },
    {
      "id": "error.log"
    },
    {
      "id": "error.log.4"
    },
    {
      "id": "run_erl.log"
    }
  ],
  "links": {
    "self": "/explore/clusters/localdev/nodes/dev1@127.0.0.1/log/files"
  }
}

Response 404

HideShow

Headers

Content-Type: text/html

Node Log File ¶

Retrieve a Log File for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/log/files/{file_name}?rows={rows}`

Retrieves the results of tailing a specific log file that belongs to a node. (Equivalent to tail -n 1000 $log_file_name, by default). Only the log files that reside in the Riak node’s log directory are allowed (that is, only the files that appear in the response to .../log/files).

Example URI

GET http://localhost:9000/explore/clusters/localdev/nodes/dev1@127.0.0.1/log/files/console.log?rows=5

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
node_id: string (required) Example: dev1@127.0.0.1
The Riak node id (in distributed Erlang node format).
file_name: string (required) Example: console.log
Name of the log file.
rows: integer (optional) Default: 1000 Example: 5
Number of lines (from the end of the log) to return. Similar to the command line tail -n $rows.

Response 200

HideShow

Headers

Content-Type: plain/text
Accept: plain/text

Body

2015-12-14 12:36:23.709 [info] <0.20541.0>@re_riak_patch:check_existence:135 Checking ./etc/advanced.config exists... true
2015-12-14 12:36:23.709 [info] <0.20541.0>@re_riak_patch:check_existence:135 Checking ./etc/vm.args exists... false
2015-12-14 12:36:23.708 [info] <0.20541.0>@re_riak_patch:check_existence:135 Checking ./etc/app.config exists... false
2015-12-14 12:36:23.588 [info] <0.20541.0>@re_riak_patch:check_existence:135 Checking ./etc/riak.conf exists... true

Response 404

HideShow

Headers

Content-Type: text/html

Bucket Types Collection ¶

List all Bucket Types
GET`/explore/clusters/bucket_types`

Return all bucket types that exist on the cluster, both active and inactive. Equivalent to running riak-admin bucket-type list on the command line. Also includes each bucket type’s properties hash (the equivalent of riak-admin bucket-type status $type).

Unlike the command-line version, this API request returns the list of bucket types sorted alphabetically.

Example URI

GET http://localhost:9000/explore/clusters/bucket_types

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "bucket_types": [
    {
      "id": "default",
      "props": {
        "active": true,
        "allow_mult": false,
        "basic_quorum": false,
        "big_vclock": 50,
        "chash_keyfun": "{riak_core_util,chash_std_keyfun}",
        "dvv_enabled": false,
        "dw": "quorum",
        "last_write_wins": false,
        "linkfun": "{modfun,riak_kv_wm_link_walker,mapreduce_linkfun}",
        "n_val": 3,
        "notfound_ok": true,
        "old_vclock": 86400,
        "postcommit": [],
        "pr": 0,
        "precommit": [],
        "pw": 0,
        "r": "quorum",
        "rw": "quorum",
        "small_vclock": 50,
        "w": "quorum",
        "write_once": false,
        "young_vclock": 20
      }
    },
    {
      "id": "users",
      "props": {
        "active": true,
        "allow_mult": true,
        "basic_quorum": false,
        "big_vclock": 50,
        "chash_keyfun": "{riak_core_util,chash_std_keyfun}",
        "claimant": "'riak@127.0.0.1'",
        "dvv_enabled": true,
        "dw": "quorum",
        "last_write_wins": false,
        "linkfun": "{modfun,riak_kv_wm_link_walker,mapreduce_linkfun}",
        "n_val": 3,
        "notfound_ok": true,
        "old_vclock": 86400,
        "postcommit": [],
        "pr": 0,
        "precommit": [],
        "pw": 0,
        "r": "quorum",
        "rw": "quorum",
        "search_index": "users_index",
        "small_vclock": 50,
        "w": "quorum",
        "young_vclock": 20
      }
    }
  ]
}

Bucket Type ¶

Retrieve a Bucket Type
GET`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}`

Returns the properties hash for the specified bucket type (the equivalent of running riak-admin bucket-type status $type on the command line).

Example URI

GET http://localhost:9000/explore/clusters/localdev/bucket_types/default

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "bucket_type": {
    "id": "default",
    "props": {
      "active": true,
      "allow_mult": false,
      "basic_quorum": false,
      "big_vclock": 50,
      "chash_keyfun": "{riak_core_util,chash_std_keyfun}",
      "dvv_enabled": false,
      "dw": "quorum",
      "last_write_wins": false,
      "linkfun": "{modfun,riak_kv_wm_link_walker,mapreduce_linkfun}",
      "n_val": 3,
      "notfound_ok": true,
      "old_vclock": 86400,
      "postcommit": [],
      "pr": 0,
      "precommit": [],
      "pw": 0,
      "r": "quorum",
      "rw": "quorum",
      "small_vclock": 50,
      "w": "quorum",
      "write_once": false,
      "young_vclock": 20
    }
  },
  "links": {
    "self": "/explore/clusters/localdev/bucket_types/default"
  }
}

Response 404

Cached Bucket List ¶

Listing buckets is a prohibitively expensive operation in Riak, due to it being a distributed K/V store based on consistent hashing. Although the List Buckets command exists, executing it on a production cluster with a non-trivial dataset can have a catastrophic impact on its resources, and is strictly not recommended.

To provide a better developer experience while working within this limitation, Riak Explorer stores a cached bucket list (as a plain newline-separated text file) on the API side, located in $explorer_dir/data/buckets/{cluster_id}/{bucket_type_id}/. The filename for the cached list is based on the timestamp at which the cache was generated.

While a cluster is in development mode, this cached list can be automatically populated from a Streaming List Buckets request. In Production mode (setting clusters.{cluster_id}.development_mode = off in riak_explorer.conf), the List Buckets functionality is disabled. However, users can still provide their own cached bucket list, either by generating it elsewhere (like on a separate Staging cluster), or by editing the bucket list directly through the Explorer GUI.

Clear a Cached Bucket List
DELETE`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets`

Clears the entire cached bucket list for the given bucket type (deletes the cached text file on the API side).

Example URI

DELETE http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.

Response 204

Edit a Cached Bucket List
PUT`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets`

Example URI

PUT http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.

Request

HideShow

Headers

Content-Type: plain/text

Body

accounts
books
authors
users

Response 204

Paginated Cached Bucket List ¶

Given that there is no limit to the number of buckets that can exist within a bucket type, the cached list can get rather large. A pagination API is provided for client convenience.

Retrieve a Paginated Cached Bucket List
GET`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets?start={start}&rows={rows}`

Retrieves the cached bucket list for a given bucket type, with pagination controls parameters.

Returns a 404 Object Not Found if no cached list exists on the API side (note that this doesn’t mean that no buckets actually exist, in the cluster).

Example URI

GET http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets?start=1&rows=500

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.
start: integer (optional) Default: 1 Example: 1
Which bucket to start from, counting from the start of the list. Used for pagination.
rows: integer (optional) Default: 1000 Example: 500
How many buckets to return in the response. Used for pagination.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "buckets": {
    "buckets": [
      "accounts",
      "transactions",
      "users"
    ],
    "count": 3,
    "created": "2015-12-16 15:23:24",
    "total": 3
  },
  "links": {
    "self": "/explore/clusters/production1/bucket_types/default/buckets"
  }
}

Response 404

Cache Refresh from Streaming List Buckets ¶

(Development Mode Only) As a convenience to developers, Explorer can automatically populate a cached bucket list from the result of a Streaming List Buckets request to Riak.

Refresh the Cached Bucket List
POST`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/refresh_buckets/source/riak_kv?sort={sort}`

Kicks off a Refresh Job to populate a bucket type’s cached bucket list from a Streaming List Buckets request.

Since the List Buckets results arrive in random order, a sort parameter is also provided.

When used in Production Mode, requests made to this API endpoint result in an HTTP 403 Forbidden.

Example URI

POST http://localhost:9000/explore/clusters/localdev/bucket_types/default/refresh_buckets/source/riak_kv?sort=true

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.
sort: boolean (optional) Default: true Example: true
Sorts the cached list in alphabetical order if set to true.

Response 204

Response 403

Cached Key List ¶

Listing keys is a prohibitively expensive operation in Riak, due to it being a distributed K/V store based on consistent hashing. Although the List Keys command exists, executing it on a production cluster with a non-trivial dataset can have a catastrophic impact on its resources, and is strictly not recommended.

To provide a better developer experience while working within this limitation, Riak Explorer stores a cached key list (as a plain newline-separated text file) on the API side, located in $explorer_dir/data/buckets/{cluster_id}/{bucket_type_id}/{bucket_id}/. The filename for the cached list is based on the timestamp at which the cache was generated.

While a cluster is in development mode, this cached list can be automatically populated from a Streaming List Keys request. In Production mode (setting clusters.{cluster_id}.development_mode = off in riak_explorer.conf), the List Keys functionality is disabled. However, users can still provide their own cached key list, either by generating it elsewhere (like on a separate Staging cluster), or by editing the key list directly through the Explorer GUI.

Clear a Cached Key List
DELETE`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets/{bucket_id}/keys`

Clears the entire cached key list for the given bucket type (deletes the cached text file on the API side).

Example URI

DELETE http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets/users/keys

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.
bucket_id: string (required) Example: users
The bucket name (unique within the bucket type).

Response 204

Edit a Cached Key List
PUT`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets/{bucket_id}/keys`

Example URI

PUT http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets/users/keys

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
bucket_type_id: string (required) Example: default
The name of the Riak Bucket Type.
bucket_id: string (required) Example: users
The bucket name (unique within the bucket type).

Request

HideShow

Headers

Content-Type: plain/text

Body

user1
user3
user4
user5

Response 204

Paginated Cached Key List ¶

Given that there is no limit to the number of keys that can exist within a bucket, the cached key list can get extremely large. A pagination API is provided for client convenience.

Retrieve a Paginated Cached Key List
GET`/explore/clusters/{cluster_id}/bucket_types/{type_id}/buckets/{bucket_id}/keys?start={start}&rows={rows}`

Retrieves the cached key list for a given bucket type, with pagination controls parameters.

Returns a 404 Object Not Found if no cached list exists on the API side (note that this doesn’t mean that no keys actually exist in that bucket, in the actual cluster).

Example URI

GET http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets/users/keys?start=1&rows=500

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
type_id: string (required) Example: default
The name of the Riak Bucket Type.
bucket_id: string (required) Example: users
The bucket name (unique within the bucket type).
start: integer (optional) Default: 1 Example: 1
Which key to start from, counting from the start of the list. Used for pagination.
rows: integer (optional) Default: 1000 Example: 500
How many keys to return in the response. Used for pagination.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "keys": {
    "count": 3,
    "created": "2015-12-15 16:42:19",
    "keys": [
      "user1",
      "user2",
      "user3"
    ],
    "total": 3
  },
  "links": {
    "self": "/explore/clusters/production1/bucket_types/default/buckets/users/keys"
  }
}

Response 404

Cache Refresh from Streaming List Keys ¶

(Development Mode Only) As a convenience to developers, Explorer can automatically populate a cached key list from the result of a Streaming List Keys request to Riak.

Refresh the Cached Key List
POST`/explore/clusters/{cluster_id}/bucket_types/{type_id}/buckets/{bucket_id}/refresh_keys/source/riak_kv?sort={sort}`

Kicks off a Refresh Job to populate a bucket’s cached key list from a Streaming List Key request.

Since the List Keys results arrive in random order, a sort parameter is also provided.

When used in Production Mode, requests made to this API endpoint result in an HTTP 403 Forbidden.

Example URI

POST http://localhost:9000/explore/clusters/localdev/bucket_types/default/buckets/users/refresh_keys/source/riak_kv?sort=true

URI Parameters

HideShow

cluster_id: string (required) Example: localdev
The Cluster id.
type_id: string (required) Example: default
The name of the Riak Bucket Type.
bucket_id: string (required) Example: users
The bucket name (unique within the bucket type).
sort: boolean (optional) Default: true Example: true
Sorts the cached list in alphabetical order if set to true.

Response 204

Response 403

Group Riak Proxy ¶

The /riak set of endpoints allow for clients to proxy requests to nodes in the cluster.

Riak Ping ¶

Ping a Riak Node
GET`/riak/nodes/{node_id}/ping`

Performs an HTTP riak ping and returns the result.

Example URI

GET http://localhost:9000/riak/nodes/riak1@127.0.0.1/ping

URI Parameters

HideShow

node_id: string (required) Example: riak1@127.0.0.1
The Riak node id (in distributed Erlang node format).

Response 200

HideShow

Headers

Content-Type: text/html

Body

OK

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Node is not running."
}

Preflist for a Key ¶

Introduced in Riak 2.1.2 (in riak_kv PR #1083), as a result of a mailing list answer by Charlie Voiselle.

Retrieve Preflist for Riak Object
GET`/riak/clusters/{cluster}/types/{type}/buckets/{bucket}/keys/{key}/preflist`

Retrieves a list of partitions and nodes for a given riak object.

Example URI

GET http://localhost:9000/riak/clusters/localdev/types/default/buckets/users/keys/user123/preflist

URI Parameters

HideShow

cluster: string (required) Example: localdev
The Cluster id.
type: string (required) Example: default
The name of the Riak Bucket Type.
bucket: string (required) Example: users
The bucket name (unique within the bucket type).
key: string (required) Example: user123
Riak object key.

Response 200

HideShow

Body

{
  "preflist": [
    {
      "node": "dev1@127.0.0.1",
      "partition": 29,
      "primary": true
    },
    {
      "node": "dev2@127.0.0.1",
      "partition": 30,
      "primary": true
    },
    {
      "node": "dev3@127.0.0.1",
      "partition": 31,
      "primary": true
    }
  ]
}

Resource Group ¶

Group Explore ¶

Explorer Ping ¶

Get Ping ResultGET/explore/ping

Example URI

Headers

Body

Clusters Collection ¶

List All ClustersGET/explore/clusters

Example URI

Headers

Body

Cluster ¶

Retrieve a ClusterGET/explore/clusters/{cluster_id}

Example URI

Headers

Body

Headers

Nodes Collection ¶

List all NodesGET/explore/clusters/nodes

Example URI

Headers

Body

Headers

Node ¶

Retrieve a NodeGET/explore/clusters/{cluster_id}/nodes/{node_id}

Example URI

Headers

Body

Headers

Node Effective Config ¶

Retrieve a Node's effective configGET/explore/clusters/{cluster_id}/nodes/{node_id}/config

Example URI

Headers

Body

Headers

Body

Node Config Files Collection ¶

List all config files for a NodeGET/explore/clusters/{cluster_id}/nodes/{node_id}/config/files

Example URI

Headers

Body

Node Config File ¶

Retrieve a Config File for a NodeGET/explore/clusters/{cluster_id}/nodes/{node_id}/config/files/{file_name}

Example URI

Headers

Body

Headers

Node Log Files Collection ¶

List all Log Files for a NodeGET/explore/clusters/{cluster_id}/nodes/{node_id}/log/files

Example URI

Headers

Body

Headers

Node Log File ¶

Retrieve a Log File for a NodeGET/explore/clusters/{cluster_id}/nodes/{node_id}/log/files/{file_name}?rows={rows}

Example URI

Headers

Body

Headers

Bucket Types Collection ¶

List all Bucket TypesGET/explore/clusters/bucket_types

Example URI

Headers

Body

Bucket Type ¶

Retrieve a Bucket TypeGET/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}

Example URI

Headers

Body

Cached Bucket List ¶

Clear a Cached Bucket ListDELETE/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets

Example URI

Edit a Cached Bucket ListPUT/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets

Example URI

Headers

Body

Paginated Cached Bucket List ¶

Retrieve a Paginated Cached Bucket ListGET/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets?start={start}&rows={rows}

Example URI

Get Ping Result
GET`/explore/ping`

List All Clusters
GET`/explore/clusters`

Retrieve a Cluster
GET`/explore/clusters/{cluster_id}`

List all Nodes
GET`/explore/clusters/nodes`

Retrieve a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}`

Retrieve a Node's effective config
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/config`

List all config files for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/config/files`

Retrieve a Config File for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/config/files/{file_name}`

List all Log Files for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/log/files`

Retrieve a Log File for a Node
GET`/explore/clusters/{cluster_id}/nodes/{node_id}/log/files/{file_name}?rows={rows}`

List all Bucket Types
GET`/explore/clusters/bucket_types`

Retrieve a Bucket Type
GET`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}`

Clear a Cached Bucket List
DELETE`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets`

Edit a Cached Bucket List
PUT`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets`

Retrieve a Paginated Cached Bucket List
GET`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets?start={start}&rows={rows}`

Refresh the Cached Bucket List
POST`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/refresh_buckets/source/riak_kv?sort={sort}`

Clear a Cached Key List
DELETE`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets/{bucket_id}/keys`

Edit a Cached Key List
PUT`/explore/clusters/{cluster_id}/bucket_types/{bucket_type_id}/buckets/{bucket_id}/keys`

Retrieve a Paginated Cached Key List
GET`/explore/clusters/{cluster_id}/bucket_types/{type_id}/buckets/{bucket_id}/keys?start={start}&rows={rows}`

Refresh the Cached Key List
POST`/explore/clusters/{cluster_id}/bucket_types/{type_id}/buckets/{bucket_id}/refresh_keys/source/riak_kv?sort={sort}`

Ping a Riak Node
GET`/riak/nodes/{node_id}/ping`

Retrieve Preflist for Riak Object
GET`/riak/clusters/{cluster}/types/{type}/buckets/{bucket}/keys/{key}/preflist`