Skip to content

Webservice Response

The Webservice Response op allows the rule to control the HTTP response params in webservice rules.

The final response is built from stash variables. This op will convert the input response YAML into stash parameters that will call the corresponding response methods.

This op has no effect on rule types different from Webservice rules.

Read more on Webservice Rules to better understand the context behind this op.

Response YAML configuration

The only configuration parameter for this op is a YAML field called Response.

The YAML response is a map/dictionary data structure (also called hash). The following keys are valid:

  • body:
  • data:
  • headers:
  • cookies:
  • location:
  • status:

Using variables in the response

Stash variables can used anywhere in the YAML:

data:
   my_key: ${some_stash_variable}
   your_location: ${ws_request.location}

body: (mutually exclusive with 'data:')

The body: is a string that will be sent back to the webservice requestor as is. This is the recommended response when sending text data or file contents.

Warning

The data: and body: entries are mutually exclusive.

data: (mutually exclusive with 'body:')

Holds a key-value map of data for a JSON, XML or YAML response.

For example, the following response YAML:

data:
   name: Me
   address: 123 Elm St.

Will yield the following Response JSON:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8

{ "name": "Me", "address": "123 Elm St." }

Warning

The data: and body: entries are mutually exclusive.

headers:

A key-value map of headers to be sent as a response:

headers:
   content_type: application/csv
   Content-Disposition: attachment;filename=example.csv

The keys will be capitalized and spaces and underscores will be converted to dashes, to make them compatible with the HTTP protocol and web standards.

cookies:

This is a header helper to make it easy to send cookies as a response.

cookies:
   my-cookie:
      value: my cookie value
      expires: +3M   # relative or just a date
      max-age: +2D   # same as expires, but relative
      path: /  # cookie only returned to matching paths
      domain: mydomain # controls which domains will get the cookie
      secure: 1
      httponly: 1  # makes the cookie unnacessible through Javascript

content_type:

This will set the Content-Type response header. It's a shortcut to headers: { content_type: ... }.

content_type: application/json
data:
   somekey: 123

status:

Sets the response HTTP status.

Typically, one does not need to set the status, as this is done automatically by the Clarive server when generating the final webservice response.

If a value is set, it will overwrite the server response.

Be aware setting an incorrect HTTP status may cause undesired behavior at any of the endpoints along the request-response path.

location:

Sets the location response header. This is just a shortcut to headers: { location: .... }

Webservice Request URL

To further control the response, it's important to use the correct calling URL to the webservice rule.

The meaning of the data: (and body:) parameters depend on the request URL format path part to the rule. This means the same rule could be called with different data format requests: json, xml, raw.

Meanings of the data: parameter:

  • https://clariveserver/rule/raw/: YAML
  • https://clariveserver/rule/json/: JSON
  • https://clariveserver/rule/xml/: XML

Meanings of the body: parameter:

  • https://clariveserver/rule/raw/: YAML
  • https://clariveserver/rule/json/: not used
  • https://clariveserver/rule/xml/: the string contents of body is wrapped within the following XML template <clarive>(body)</clarive>, and body will be translated to the corresponding data structure.