Get the cluster topology

GET

/v2/topology

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/topology"))
    .header("Authorization", "Bearer <token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/topology';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:8080/v2/topology \
  --header 'Authorization: Bearer <token>'

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session · requires operations:health

The nodes of the cluster and the partitions each one runs, as the official clients and the connector runtime read it for their health check. Every node that owns partitions is a broker leading them; a partition is healthy while its owner’s lease is live. The log is kept in PostgreSQL, so there are no followers and the replication factor is 1. A single-node engine answers one broker leading one partition, at the address it was reached at. Every authenticated client may read it, whatever its permissions.

Authorizations

bearerAuth
sessionCookie

Responses

200

The cluster topology.

application/json

object

brokers

required

Array<object>

object

nodeId

required

integer format: int32

brokerId

required

The nodeId as text.

string

host

required

string

port

required

integer format: int32

partitions

required

Array<object>

object

partitionId

required

integer format: int32

role

required

Every partition a node owns

string

Allowed values: leader

health

required

string

Allowed values: healthy unhealthy

state

required

string

Allowed values: active

version

required

string

clusterId

required

Always null.

string | null

clusterSize

required

The number of nodes that own partitions.

integer format: int32

partitionsCount

required

integer format: int32

replicationFactor

required

Always 1.

integer format: int32

gatewayVersion

required

string

lastCompletedChangeId

required

Always -1.

string

Example

{
  "brokers": [
    {
      "partitions": [
        {
          "role": "leader",
          "health": "healthy",
          "state": "active"
        }
      ]
    }
  ]
}

401

No valid credential was presented.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid bearer credential is required",
  "instance": "/v2/topology"
}

Headers

WWW-Authenticate

string

Allowed value: Bearer

403

The caller lacks the required permission, a tenant named in the request is not the caller’s tenant, or a cookie write has no valid CSRF token.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The principal lacks the action this route requires",
  "instance": "/v2/topology"
}

500

An internal failure. The details are never exposed.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:internal",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The request could not be completed",
  "instance": "/v2/topology"
}

503

Backpressure, or a dependency is not ready. Retry with the same idempotency key.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The required engine service is not ready",
  "instance": "/v2/topology"
}