# 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](/reference/servoyextensions/server-plugins/rest_ws/wscookie.md) | [createCookie(name, value)](#createcookie-name-value) | Create a http cookie. | | [WsRequest](/reference/servoyextensions/server-plugins/rest_ws/wsrequest.md) | [getRequest()](#getrequest) | Get the currently running REST-WS request. | | [WsResponse](/reference/servoyextensions/server-plugins/rest_ws/wsresponse.md) | [getResponse()](#getresponse) | Get the response for the currently running REST-WS request. | | [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) | [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](/reference/servoycore/dev-api/js-lib/string.md) **name** The name of the cookie * [String](/reference/servoycore/dev-api/js-lib/string.md) **value** The value of the cookie **Returns:** [WsCookie](/reference/servoyextensions/server-plugins/rest_ws/wscookie.md) 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](/reference/servoyextensions/server-plugins/rest_ws/wsrequest.md) 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](/reference/servoyextensions/server-plugins/rest_ws/wsresponse.md) 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](/reference/servoycore/dev-api/js-lib/boolean.md) 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](/reference/servoycore/dev-api/js-lib/boolean.md) **send** ; **Returns:** void *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.servoy.com/reference/servoyextensions/server-plugins/rest_ws.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.