# rest\_ws

(plugins.rest\_ws)

## Overview

The `rest_ws` client represents a REST-WS client instance, valid only during a running REST-WS request. It provides methods for managing HTTP cookies, accessing the current request and response, checking request status, and controlling the inclusion of user properties in response headers.

The `createCookie(name, value)` method creates an HTTP cookie using specified name and value parameters, which must conform to the cookie specification. The resulting `WsCookie` object can be added to a response using `getResponse()`. The `getRequest()` and `getResponse()` methods provide access to the current REST-WS request and its corresponding response. These methods throw exceptions if invoked outside a REST-WS context, ensuring accurate usage within valid workflows.

To determine if the client is running in a REST-WS context, `isRunningRequest()` returns a boolean value. When enabled, this facilitates conditional logic based on the REST-WS state.

Finally, the `sendResponseUserPropertiesHeaders(send)` method enables or disables the inclusion of user properties as response headers. By default, these headers are sent, but this behavior can be controlled using the `send` parameter.

## Methods Summarized

| Type                                               | Name                                                                               | Summary                                                               |
| -------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [WsCookie](rest_ws/wscookie)                       | [createCookie(name, value)](#createcookie-name-value)                              | Create a http cookie.                                                 |
| [WsRequest](rest_ws/wsrequest)                     | [getRequest()](#getrequest)                                                        | Get the currently running REST-WS request.                            |
| [WsResponse](rest_ws/wsresponse)                   | [getResponse()](#getresponse)                                                      | Get the response for the currently running REST-WS request.           |
| [Boolean](../../servoycore/dev-api/js-lib/boolean) | [isRunningRequest()](#isrunningrequest)                                            | Check whether the client is currently running a REST-WS request.      |
| void                                               | [sendResponseUserPropertiesHeaders(send)](#sendresponseuserpropertiesheaders-send) | Allow or block sending the user properties as response header values. |

## Methods Detailed

### createCookie(name, value)

Create a http cookie.\
The cookie name and value allows only a sequence of non-special, non-white space characters, see\
the cookie spec https://tools.ietf.org/html/rfc2965

**Parameters**

* [String](../../servoycore/dev-api/js-lib/string) **name** The name of the cookie
* [String](../../servoycore/dev-api/js-lib/string) **value** The value of the cookie

**Returns:** [WsCookie](rest_ws/wscookie) A \`WsCookie\` object representing the created HTTP cookie.

**Sample**

```js
var cookie = plugins.rest_ws.createCookie('chocolate', 'chip');
var response = plugins.rest_ws.getResponse();
response.addCookie(cookie);
```

### getRequest()

Get the currently running REST-WS request.\
&#x20;If the client is not currently running in REST-WS, an exception is thrown.

**Returns:** [WsRequest](rest_ws/wsrequest) The currently active REST-WS request as a \`WsRequest\` object.

### getResponse()

Get the response for the currently running REST-WS request.\
If the client is not currently running in REST-WS, an exception is thrown.

**Returns:** [WsResponse](rest_ws/wsresponse) The response associated with the currently active REST-WS request as a \`WsResponse\` object.

**Sample**

```js
var response = plugins.rest_ws.getResponse();
resp.setHeader("My-Custom-Header", "42");
```

### isRunningRequest()

Check whether the client is currently running a REST-WS request.\
&#x20;If false, the rest-ws client-plugin features are not available.

**Returns:** [Boolean](../../servoycore/dev-api/js-lib/boolean) true if the client is currently handling a REST-WS request, false otherwise.

### sendResponseUserPropertiesHeaders(send)

Allow or block sending the user properties as response header values.\
By default the response headers contain the user properties.

**Parameters**

* [Boolean](../../servoycore/dev-api/js-lib/boolean) **send** ;

**Returns:** void

***
