# 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. ## Properties | Property | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `rest_ws_plugin_authorized_groups` | Only authenticated users in the listed groups (comma-separated) have access, when left empty unauthorised access is allowed | | `rest_ws_send_user_properties_headers` | This is a global setting to specify if the user properties are generated as header values on the REST responses. It can also be set in the rest ws plugin ws\_\* methods. Default is true. | | `rest_ws_use_jsupload_for_binary_data` | Convert binary uploads (multipart or pure byte uploads) to a JSUpload that is cached on disk if they are bigger then a threshold (servoy.ng\_web\_client.tempfile.threshold property), default 'true' | | `rest_ws_plugin_client_pool_size` | Max number of clients per solution used (this defines the number of concurrent requests and licences used per solution), default = 5. The same value is used for maximum number of idle clients. In case of rest\_ws\_plugin\_client\_pool\_exhausted\_action=grow, the number of clients may become higher. When running in developer this setting is ignored, pool size will always be 1 | | `rest_ws_plugin_client_pool_exhausted_action` | The following values are supported for this setting: | | block (default): requests will wait untill a client becomes available, when running in developer this value will be used | | | fail: the request will fail. The API will generate a SERVICE\_UNAVAILABLE response (HTTP 503) | | | grow: allows the pool to grow, by starting additional clients. The number of clients per solution may become higher than defined by setting 'rest\_ws\_plugin\_client\_pool\_size', but will shrink back to that value when clients in the pool become idle. | | | `rest_ws_plugin_client_max_grow_pool_size` | This value is only used when rest\_ws\_plugin\_client\_pool\_exhausted\_action=grow, and it defines the total number of clients to which the pool grows, after this value the pool will block. By default is not defined. | ## Methods Summarized | Type | Name | Summary | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | [WsCookie](https://docs.servoy.com/reference/servoyextensions/server-plugins/rest_ws/wscookie) | [createCookie(name, value)](#createcookie-name-value) | Create a http cookie. | | [WsRequest](https://docs.servoy.com/reference/servoyextensions/server-plugins/rest_ws/wsrequest) | [getRequest()](#getrequest) | Get the currently running REST-WS request. | | [WsResponse](https://docs.servoy.com/reference/servoyextensions/server-plugins/rest_ws/wsresponse) | [getResponse()](#getresponse) | Get the response for the currently running REST-WS request. | | [Boolean](https://docs.servoy.com/reference/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 **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** The name of the cookie * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** The value of the cookie **Returns:** [WsCookie](https://docs.servoy.com/reference/servoyextensions/server-plugins/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.\ If the client is not currently running in REST-WS, an exception is thrown. **Returns:** [WsRequest](https://docs.servoy.com/reference/servoyextensions/server-plugins/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](https://docs.servoy.com/reference/servoyextensions/server-plugins/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.\ If false, the rest-ws client-plugin features are not available. **Returns:** [Boolean](https://docs.servoy.com/reference/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](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) **send** ; **Returns:** void ***