CockroachDB v2 API

CockroachDB v2 APIv2.0.0

API for querying information about CockroachDB health, nodes, ranges, sessions, and other meta entities.

License Business Source License

Servers

 

:

http://localhost/api/v2

:

https://localhost/api/v2
 

Health

 

GET /health/

Helper endpoint to check for node health. If ready is true, it also checks if this node is fully operational and ready to accept SQL connections. Otherwise, this endpoint always returns a successful response (if the API server is up, of course).

/health/?ready=value

Query Parameters

ready optional

If true, check whether this node is ready to accept SQL connections. If false, this endpoint always returns success, unless the API server itself is down.

Responses

200 OK
500 Internal Server Error

Login

 

POST /login/

Creates an API session for use with API endpoints that require authentication.

/login/

Request Body

Content-Type: application/x-www-form-urlencoded{"type"=>"object", "required"=>["username", "password"], "properties"=>{"password"=>{"type"=>"string"}, "username"=>{"type"=>"string"}}}

Responses

200 OKContent-Type: application/json{
  "session": "string"
}Content-Type: text/plain{"$ref"=>"#/components/schemas/loginResponse"}
400 Bad Request
401 Unauthorized

Logout

 

POST /logout/

Logs out on a previously-created API session.

/logout/

Responses

200 OKContent-Type: application/json{
  "logged_out": "boolean"
}Content-Type: text/plain{"$ref"=>"#/components/schemas/logoutResponse"}
400 Bad Request

Nodes

 

GET /nodes/

List all nodes on this cluster.

Client must be logged-in as a user with admin privileges.

/nodes/?limit=value&offset=value

Query Parameters

limit optional

Maximum number of results to return in this call.
offset optional

Continuation token for results after a past limited run.

Responses

200 OKContent-Type: application/json{
  "next": "integer",
  "nodes": []
}

GET /nodes/{node_id}/ranges/

Lists information about ranges on a specified node. If a list of range IDs is specified, only information about those ranges is returned.

Client must be logged-in as a user with admin privileges.

/nodes/{node_id}/ranges/?ranges=value&limit=value&offset=value

Path Parameters

node_id required

ID of node to query, or local for local node.

Query Parameters

ranges optional

IDs of ranges to return information for. All ranges returned if unspecified.
limit optional

Maximum number of results to return in this call.
offset optional

Continuation token for results after a past limited run.

Responses

200 OKContent-Type: application/json{
  "next": "integer",
  "ranges": []
}

Ranges

 

GET /ranges/hot/

Lists information about hot ranges. If a list of range IDs is specified, only information about those ranges is returned.

Client must be logged-in as a user with admin privileges.

/ranges/hot/?node_id=value&limit=value&start=value

Query Parameters

node_id optional

ID of node to query, or local for local node. If unspecified, all nodes are queried.
limit optional

Maximum number of results to return in this call.
start optional

Continuation token for results after a past limited run.

Responses

200 OKContent-Type: application/json{
  "next": "string",
  "ranges_by_node_id": {},
  "response_error": []
}

GET /ranges/{range_id}/

Retrieves more information about a specific range.

Client must be logged-in as a user with admin privileges.

/ranges/{range_id}/

Path Parameters

range_id required

Responses

200 OKContent-Type: application/json{
  "responses_by_node_id": {}
}

Sessions

 

GET /sessions/

List all sessions on this cluster. If a username is provided, only sessions from that user are returned.

Client must be logged-in as a user with admin privileges.

/sessions/?username=value&limit=value&start=value

Query Parameters

username optional

Username of user to return sessions for; if unspecified, sessions from all users are returned.
limit optional

Maximum number of results to return in this call.
start optional

Continuation token for results after a past limited run.

Responses

200 OKContent-Type: application/json{
  "errors": [],
  "next": "string",
  "sessions": []
}