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
When requesting a Server's state in an XML format, you may receive a document as follows.
<state-component
state="ENDING"
future-state="MAINTENANCE"
initiator="system\admin"
grace-end="2016-12-29T17:51:20+0100"
grace-period="575509"
component-count="2"
href="http://localhost:13442/state">
<state-component
name="License Key Server"
component-count="0"
state="MAINTENANCE"
href="http://localhost:13442/state/License%20Key%20Server"/>
<state-component
name="Web Application Container"
component-count="20"
state="ENDING"
href="http://localhost:13442/state/Web%20Application%20Container"/>
</state-component>
In the preceding XML, only the state, component-count and href attributes are always specified on the top-level element.
The initiator attribute will contain the user name of the person that most recently performed a state change and will remain unspecified
for as long as no state change has yet been performed during the runtime of the Server program.
The attributes future-state, grace-end and grace-period (remaining time in milliseconds) are only specified when a state change with explicit grace period is currently in progress.
When a graceful state change has been initiated without an explicit grace period, the grace-end attribute is absent and grace-period will contain -1.
Each child element of the XML corresponds with a state-aware component in the Server.
Each element has attributes containing the name of the component, its current state, the number of subcomponents it manages and
an href attribute that can be used to retrieve more information about that component's subcomponents.
It is also possible to include subcomponent information in the resulting XML by specifying a depth query parameter with a value of 3."When requesting a Server's state in JSON format, you may receive a document as follows."
{ "state":"ENDING",
"futureState":"MAINTENANCE",
"initiator":"system\admin",
"graceEnd":"2016-12-29T17:51:20+0100",
"gracePeriod":575509,
"componentCount":2,
"url":"http://localhost:13442/state",
"stateComponents":[
{ "name":"License Key Server",
"properties":null,
"state":"MAINTENANCE",
"url":"http://localhost:13442/state/License%20Key%20Server",
"componentCount":0,
"stateComponents":[]
},
{ "name":"Web Application Container",
"properties":null,
"state":"ENDING",
"url":"http://localhost:13442/state/Web%20Application%20Container",
"componentCount":20,
"stateComponents":[]
}
]
}
"In JSON, all potential fields are always specified, but some may have a null or empty array value. The semantics of the fields are identical to the corresponding attributes in XML."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
When changing a Server's state by posting an XML, you must send a state-component document in which you mention the desired result state. Allowed values are RUNNING, MAINTENANCE, and STOPPED. Intermediate states cannot be explicitly set, but are automaticaly passed through if necessary.
You can specify an explicit grace period by providing a fixed end time in ISO-8601 format, or by providing a period in milliseconds. When specifying both a time and a period, the time takes precedence.
If you want to perform a graceful state change without an explicit end time to the grace period, specify a negative value for the grace-period attribute.
Using the REST API it is possible to modify an individual component's state (e.g. place a single component in the Running state while the rest of the Server remains in Maintenance state). When the state of individual components does not match the Server's global state and you want to place those components in the same state as the Server, you will either have to change each individual component's state, or you can invoke a state change on the Server while setting the force-recursive attribute to true.
<state-component
future-state="MAINTENANCE"
grace-period="600000"/>
In the preceding XML, the Server is placed in Maintenance state with an explicit grace period of 10 minutes.
<state-component
future-state="MAINTENANCE"
grace-period="-1"/>
In the preceding XML, the Server is placed in Maintenance state with an indefinite grace period.
<state-component
future-state="MAINTENANCE"
force-recursive="true"/>
In the preceding XML, the Server is immediately placed in Maintenance state, with explicit traversal through all components and subcomponents."In JSON, the semantics of the fields are identical to the corresponding attributes in XML."
{ "futureState":"MAINTENANCE",
"gracePeriod":-1,
"forceRecursive":"true"
}
"In the preceding JSON, the Server is placed in Maintenance state with an indefinite grace period and with explicit traversal through all components and subcomponents."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
When requesting a component's state in an XML format, you may receive a document as follows.
<state-component
name="Web Application Container"
state="RUNNING"
component-count="2"
href="http://localhost:13442/state/Web%20Application%20Container">
<state-component
name="Web application: OAuth"
state="RUNNING"
component-count="0"
href="http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20OAuth">
<properties>
<property>
<name>Active connections</name>
<value>0</value>
</property>
</properties>
</state-component>
<state-component
name="Web application: Root"
state="RUNNING"
component-count="0"
href="http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20Root">
<properties>
<property>
<name>Active connections</name>
<value>1</value>
</property>
</properties>
</state-component>
</state-component>
The preceding XML details the state of a component that has subcomponents. These subcomponents in turn can be queried by following their href attribute, but in this sample no new information will be obtained because each subcomponent declares to manage zero child components.
The property elements provide (sub)compoent-specific extra information that may be of use to Operators in deciding when and/or with which grace period to change a Server's state.
Of the standard Scriptura Engage components, web applications provide a property that indicates the number of active connections, Document Flow initial steps provide a property to indicate the number of active flow instances, and the Task Consumer Step additionally provides a property to indicate how many immediate tasks it still has locally queued."When requesting a component's state in JSON format, you may receive a document as follows."
{ "name":"Web Application Container",
"properties":null,
"state":"RUNNING",
"href":"http://localhost:13442/state/Web%20Application%20Container",
"componentCount":2,
"stateComponents":[
{ "name":"Web application: OAuth",
"state":"RUNNING",
"href":"http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20OAuth",
"properties":[
{ "name":"Active connections",
"value":"0"
}
],
"componentCount":0,
"stateComponents":[]
},
{ "name":"Web application: Root",
"state":"RUNNING",
"href":"http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20Root",
"properties":[
{ "name":"Active connections",
"value":"1"
}
],
"componentCount":0,
"stateComponents":[]
}
]
}
"In JSON, all potential fields are always specified, but some may have a null or empty array value. The semantics of the fields are identical to the corresponding attributes in XML."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
When changing a component's state by posting an XML, you must send a state-component document in which you mention the desired result state. Allowed values are RUNNING, MAINTENANCE, and STOPPED. Intermediate states cannot be explicitly set, but are automaticaly passed through if necessary. Using the REST API it is possible to modify an individual (sub)component's state (e.g. place a single subcomponent in the Running state while the rest of the component and/or Server remains in Maintenance state). When the state of individual subcomponents does not match the component's global state and you want to place those subcomponents in the same state as the parent component, you will either have to change each individual subcomponent's state, or you can invoke a state change on the parent component while setting the force-recursive attribute to true.
<state-component
future-state="MAINTENANCE"/>
In the preceding XML, the component is placed in Maintenance state.
<state-component
future-state="MAINTENANCE"
force-recursive="true"/>
In the preceding XML, the component is immediately placed in Maintenance state, with explicit traversal through all subcomponents."In JSON, the semantics of the fields are identical to the corresponding attributes in XML."
{ "futureState":"MAINTENANCE",
"forceRecursive":"true"
}
"In the preceding JSON, the component is placed in Maintenance state with explicit traversal through all subcomponents."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
When requesting a component's state in an XML format, you may receive a document as follows.
<state-component
name="Web Application Container"
state="RUNNING"
component-count="2"
href="http://localhost:13442/state/Web%20Application%20Container">
<state-component
name="Web application: OAuth"
state="RUNNING"
component-count="0"
href="http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20OAuth">
<properties>
<property>
<name>Active connections</name>
<value>0</value>
</property>
</properties>
</state-component>
<state-component
name="Web application: Root"
state="RUNNING"
component-count="0"
href="http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20Root">
<properties>
<property>
<name>Active connections</name>
<value>1</value>
</property>
</properties>
</state-component>
</state-component>
The preceding XML details the state of a component that has subcomponents. These subcomponents in turn can be queried by following their href attribute, but in this sample no new information will be obtained because each subcomponent declares to manage zero child components.
The property elements provide (sub)compoent-specific extra information that may be of use to Operators in deciding when and/or with which grace period to change a Server's state.
Of the standard Scriptura Engage components, web applications provide a property that indicates the number of active connections, Document Flow initial steps provide a property to indicate the number of active flow instances, and the Task Consumer Step additionally provides a property to indicate how many immediate tasks it still has locally queued."When requesting a component's state in JSON format, you may receive a document as follows."
{ "name":"Web Application Container",
"properties":null,
"state":"RUNNING",
"href":"http://localhost:13442/state/Web%20Application%20Container",
"componentCount":2,
"stateComponents":[
{ "name":"Web application: OAuth",
"state":"RUNNING",
"href":"http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20OAuth",
"properties":[
{ "name":"Active connections",
"value":"0"
}
],
"componentCount":0,
"stateComponents":[]
},
{ "name":"Web application: Root",
"state":"RUNNING",
"href":"http://localhost:13442/state/Web%20Application%20Container/Web%20application:%20Root",
"properties":[
{ "name":"Active connections",
"value":"1"
}
],
"componentCount":0,
"stateComponents":[]
}
]
}
"In JSON, all potential fields are always specified, but some may have a null or empty array value. The semantics of the fields are identical to the corresponding attributes in XML."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 |
Responses
200 OK.
Examples
When changing a component's state by posting an XML, you must send a state-component document in which you mention the desired result state. Allowed values are RUNNING, MAINTENANCE, and STOPPED. Intermediate states cannot be explicitly set, but are automaticaly passed through if necessary. Using the REST API it is possible to modify an individual (sub)component's state (e.g. place a single subcomponent in the Running state while the rest of the component and/or Server remains in Maintenance state). When the state of individual subcomponents does not match the component's global state and you want to place those subcomponents in the same state as the parent component, you will either have to change each individual subcomponent's state, or you can invoke a state change on the parent component while setting the force-recursive attribute to true.
<state-component
future-state="MAINTENANCE"/>
In the preceding XML, the component is placed in Maintenance state.
<state-component
future-state="MAINTENANCE"
force-recursive="true"/>
In the preceding XML, the component is immediately placed in Maintenance state, with explicit traversal through all subcomponents."In JSON, the semantics of the fields are identical to the corresponding attributes in XML."
{ "futureState":"MAINTENANCE",
"forceRecursive":"true"
}
"In the preceding JSON, the component is placed in Maintenance state with explicit traversal through all subcomponents."