List a system's effective roles

GET

/systems/{name}/roles

const url = 'https://example.com/api/v1/systems/example/roles';
const options = {method: 'GET'};

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

curl --request GET \
  --url https://example.com/api/v1/systems/example/roles

Every role this system needs filled: those its standard declares (from_standard true) plus those declared directly on it, each with the types it accepts (and products it pins, if any), the components filling it, and how many more it wants before quorum (understaffed). A one-off system shows only its own. Gated by system:read; an out-of-scope system is a non-disclosing 404.

Parameters

Path Parameters

name

required

The system’s name, or a dotted address (e.g. boi.17c.$sys.av)

string

The system’s name, or a dotted address (e.g. boi.17c.$sys.av)

Responses

200

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

roles

required

Array<object> | null

object

accepted_types

required

The component_types a filling component’s product must be classified within (self or a descendant); empty accepts any type

Array<string> | null

alternate

The choice/alternate this role joins, addressed as “choice-name/alternate-name” (#626); absent when the role is unconditional. The same form the write body takes, so a read round-trips into a write

string

assigned

required

How many components fill the role

integer format: int64

assigned_to

required

The component names filling this role in this system

Array<string> | null

capacity

The most components the role will accept; null means no upper bound beyond quorum

integer format: int64

from_standard

required

True when the role is inherited from the system’s standard; false when declared on the system

boolean

impact

required

What an impaired role means for its system: outage, degraded, or none

string

label

required

string

name

required

string

pinned_products

required

If set, a filling component’s product must be one of these; empty accepts any product of an accepted type

Array<string> | null

position_labels

required

Human labels for each position within the role, by index; empty when unlabeled

Array<string> | null

positions

required

AssignedTo’s own 1-based position, index for index; not necessarily i+1, since an unassign leaves a gap rather than compacting

Array<integer> | null

quorum

required

integer format: int64

understaffed

required

How many more assignment rows the role wants before quorum, health-blind; zero when enough are assigned regardless of their own condition. See the health read’s short for the occupancy-aware figure

integer format: int64

system

required

string

Example

{
  "$schema": "/api/v1/schemas/ListSystemRolesOutputBody.json"
}

default

Error

application/problem+json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

Example

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}