Using the state REST API
The following sections describe the state REST API.
Related concepts
Related tasks
Creating custom state-aware components
/state/
GET Retrieve server state
Description
Perform an authenticated HTTP GET request to obtain the current Server’s state.
The response is an XML or JSON document containing the Server’s state, information about a possible grace period that may be in progress, and a list of individual state-aware components in the Server.
The endpoint produces application/xml by default. By explicitly specifying an Accept header, the response type can be selected.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
depth | query |
Return more or less detailed information. A value of 1 will only return Server state, without listing components. A value of 2 (default) will return Server state and a list of components. A value of 3 will return Server state, a list of components and, if appliccable, subcomponents. |
Integer |
Responses
200 The response body contains the requested information.
Examples
401 The client performed the request without authentication.
403 The client does not have the required server-state:read permission.
404 The value for the depth request parameter was invalid.
Permissions
server-state:read
POST Set server state
Description
Perform an authenticated HTTP POST request to change the Server’s state. The request body is an XML or JSON document containing the desired Server state and optional grace period or grace end time.
A successful request generates no response body. An invalid request will produce a text/html or text/plain error page.
Responses
200 OK.
Examples
400 There was an error in one or more of the values in the request body or the request body is not valid XML or JSON. You also receive this error when the specified grace end time lies in the past.
401 The client performed the request without authentication.
403 The client does not have the required server-state:read permission.
Permissions
server-state:write
/state/{component-name}
GET Retrieve component state
Description
Perform an authenticated HTTP GET request to obtain the state of a specific component.
The response is an XML or JSON document containing the component’s state and a list of individual state-aware subcomponents.
The exact URI of a component’s state information can be obtained from the href attributes returned in Retrieve server state.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
component-name | path |
|
String |
depth | query |
Return more or less detailed information. A value of 1 will only return component state, without listing subcomponents. A value of 2 (default) will return component state and a list of subcomponents. A value of 3 will return component state, a list of subcomponents and, if appliccable, the child components of these subcomponents. |
Integer |
Responses
200 The response body contains the requested information.
Examples
401 The client performed the request without authentication.
403 The client does not have the required server-state:read permission.
404 The request URI does not correspond with an existing component or the value for the depth request parameter was invalid.
Permissions
server-state:read
POST Set component state
Description
Perform an authenticated HTTP POST request to change an individual component’s state.
The request body is an XML or JSON document containing the desired state.
It is not possible to specify a grace period when changing an individual component’s state.
Warning
Changing the state of an individual component is advanced functionality that may be used for debugging purposes. Using this functionality in production environments is not advised. The exact URI of a component’s state information can be obtained from the href attributes returned in Retrieve server state.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
component-name | path |
|
String |
depth | query |
Return more or less detailed information. A value of 1 will only return component state, without listing subcomponents. A value of 2 (default) will return component state and a list of subcomponents. A value of 3 will return component state, a list of subcomponents and, if appliccable, the child components of these subcomponents. |
Integer |
Responses
200 OK.
Examples
400 There was an error in one or more of the values in the request body or the request body is not valid XML or JSON.
401 The client performed the request without authentication.
403 The client does not have the required server-state:read permission.
404 The request URI does not correspond with an existing (sub)component.
Permissions
server-state:write
/state/{component-name}/{subcomponent-name}
GET Retrieve component state
Description
Perform an authenticated HTTP GET request to obtain the state of a specific subcomponent.
The response is an XML or JSON document containing the component’s state and a list of individual state-aware subcomponents.
The exact URI of a subcomponent’s state information can be obtained from the href attributes returned in Retrieve server state.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
component-name | path |
|
String |
subcomponent-name | path |
|
String |
depth | query |
Return more or less detailed information. A value of 1 will only return component state, without listing subcomponents. A value of 2 (default) will return component state and a list of subcomponents. A value of 3 will return component state, a list of subcomponents and, if appliccable, the child components of these subcomponents. |
Integer |
Responses
200 The response body contains the requested information.
Examples
401 The client performed the request without authentication.
403 The client does not have the required server-state:read permission.
404 The request URI does not correspond with an existing subcomponent or the value for the depth request parameter was invalid.
Permissions
server-state:read
POST Set component state
Description
Perform an authenticated HTTP POST request to change an individual subcomponent’s state.
The request body is an XML or JSON document containing the desired state.
It is not possible to specify a grace period when changing an individual component’s state.
Warning
Changing the state of an individual component is advanced functionality that may be used for debugging purposes. Using this functionality in production environments is not advised. The exact URI of a subcomponent’s state information can be obtained from the href attributes returned in Retrieve server state.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
component-name | path |
|
String |
depth | query |
Return more or less detailed information. A value of 1 will only return component state, without listing subcomponents. A value of 2 (default) will return component state and a list of subcomponents. A value of 3 will return component state, a list of subcomponents and, if appliccable, the child components of these subcomponents. |
Integer |