Webservice Rules

Webservice rules are rules that work similarly to webhooks, and can be launched from virtually anywhere on your network and the web.

Your Webservice rules are automatically exposed by the Clarive server under the URL http(s)://clariveserver/rule/[format]/[rulename]. These webservices are very useful to orchestate complex interactions in your DevOps pipelines and delivery value-stream.

Webservice rules receive its parameters from the web, such as the sub-path and and return data that can be translated into different formats. The return format is up to the caller to decide using the the Webservice Response op.

Request Data

The request will arrive to the rule with the following stash keys:

  • ${ws_params} - the GET or POST params as a hash/object.

  • ${ws_body} - the raw request body.

  • ${ws_headers} - the request header as a hash/object. The headers sent depend on the user agent (a browser, cURL or any language web request library). Header with keys may include Content-Type, Accept-Language and others.

  • ${ws_arguments} - an array with the URL path parts behind the URL, ie. for the URL https://clariveserver/rule/json/myrule/my/path the stash variable will hold [ 'my', 'path'].

  • ${ws_uploads} - the request uploaded file handler.

  • ${WSURL} - the URI called by the requester, in the following format schema://[authority][path].

  • ${username} - the username of the authenticated user.

  • ${ws_format} - the requested data format: json, yaml, xml, raw.

For all these, the ws_params is the most useful data. To access a certain parameter use the following variable construction:

    ${ws_params.myvar}

Response Data Formats

Possible return data formats from webservice rules are:

  • JSON
  • YAML
  • XML
  • Raw - simple plain text or binary data returned by a Rule

The caller sets the desired format in the calling URL, following the webservice URL format:

    http(s)://clariveserver/rule/[json|yaml|xml|raw]/[rule-id]

Response Content-Type will be set according to the calling URL format.

From the rule, the ${ws_format} variable can be used to determine the calling format requested by the user.

Creating a Response

To create the webservice response, please use the Webservice Response op from the palette.

The Webservice Response op can control which headers, cookies and data is returned from the server to the requesting client.

Webservice Rule Authentication

Webservice endpoints can be either authenticated or public.

Public endpoints can be accessed by anyone. Never implement public webservices that run sensitive operations. Public webservices may be useful for reporting public data as JSON, for instance.

The authentication method is through an api-key. API keys are managed on a per User basis.

Securing Webservice Rules

Besides using authenticated webservice rules, we recommend creating specific webservice-only users using the user administration, setting their permissions so that their security scope is limited to the allowed scopes, then setting the api-key for that user to be shared with specific external applications/developers.