The REST API provides the following methods for accessing the transient state:

GET /api/transientstate

URI

GET /api/transientstate

Description

Retrieves all transient state values that are visible to the calling user (in other words, values in lockers for which the caller has read access rights). A valid response is returned even if no transient state is available.

The parameter expiry is only returned if a particular transient state value is set to expire.

Request Header

Content-Type: application/json
CSRF Protection Enabled

Content-Type: application/vnd.orchestral.rhapsody.6_2+json
CSRF Protection Enabled

Request Body

None.

Response Status

200 OK - returns the transient state information in JSON format.
Response Body
Transient state available 
 {
  "data": [
    {
      "key": "myKey1",
      "locker": {
        "id": 1,
        "name": "Locker1"
      },
      "value": "myVal1",
      "expiry": "2016-05-18T23:17:13Z"
    },
    {
      "key": "myKey2",
      "locker": {
        "id": 1,
        "name": "Locker1"
      },
      "value": "myVal2"
    },
    {
      "key": "key3",
      "locker": {
        "id": 1,
        "name": "Locker1"
      },
      "value": "myVal3"
    }
  ],
  "error": null
}
No transient state available 
{
  "data": [],
  "error": null
}

Access Rights

'Read transient state REST API'.

GET /api/transientstate/<key>

URI

GET /api/transientstate/<key>

Description

Retrieves the specified transient state value using the <key> supplied in the URL, provided the transient state value exists and the caller has the appropriate access rights for the locker containing the transient state value.

The parameter expiry is only returned if the particular transient state value is set to expire.

The ETag HTTP header is set on the response if the transient state value is returned and contains a hash of the value that can optionally be subsequently used with the PUT method to perform an atomic compare and set rather than an unconditional modification.

Request Header

Accept: application/json
CSRF Protection Enabled

Accept: application/vnd.orchestral.rhapsody.6_2+json
CSRF Protection Enabled

Request Body

None.

Response Status

200 OK - returns the transient state information in JSON format.
403 Forbidden - the caller does not have permission to the appropriate configuration locker.
404 Not Found - the specified transient state value cannot be found.

Response Body 
 {

  "data": {
    "key": "myKey1",
    "locker": {
      "id": 1,
      "name": "Locker1"
    },
    "value": "myVal1",
    "expiry": "2016-05-18T23:17:13Z"
  },
  "error": null
}

Access Rights

'Read transient state REST API'.

PUT /api/transientstate/<key>

URI

PUT /api/transientstate/<key>

Description

Creates or modifies the specified transient state value for the key provided in URL as <key>.

The parameter value can be omitted or set to an empty string to clear it. The parameter expiry is optional and only required if the value should be automatically expired. If set, it must be in ISO 8601 date/time format.

By default, this performs an unconditional modification. However, the If-Exists HTTP header can optionally be provided to convert this into a conditional PUT operation. If the If-Exists header is set to *, then this remains an unconditional PUT method; if it is set to none, then the PUT method only succeeds if the specified transient state key does not currently exist; otherwise it must be set to the value returned in the ETag response header from a previous call to the GET method. If the value does not match, then a 409 Conflict status code is returned.

If a conditional PUT is performed then the compare and set operation is atomic.

Request Header

Accept: application/json
CSRF Protection Enabled

Accept: application/vnd.orchestral.rhapsody.6_2+json
CSRF Protection Enabled

Request Body

 
 {
  "lockerId": 1,
  "value": "theValue",
  "expiry": "2016-05-18T23:17:13Z"
}

Response Status

204 No Content - the modification is successful.
400 Bad Request - one of the parameters is invalid (for example, the expiry time is provided but not a valid ISO8601 timestamp), or an attempt has been made to change the owning locker of an existing transient state value. 
403 Forbidden - the caller does not have write permission for the transient state on the target configuration locker.
Response Body

Empty.

Access Rights

'Modify transient state REST API'.