- December 22, 2016

Restlet Client (formely known as DHC) is a powerful HTTP client that allows you to send, parameterize, and chain requests. It’s also possible to get their results and validate them with assertions. Also, when chaining requests, some of them will need to use the contents of a response from a previous request. To meet this need Restlet Client offers a powerful feature: expressions.

First, let’s introduce what expressions are in Restlet Client and how to use them.

Expression support

Expressions can generate, modify and link data through the application of a variety of methods. It starts with a ${, ends with a } and contains dot-separated fragments that do the manipulation. The figure below provides a first sample in Restlet Client.


When the request above is launched, the URL will be resolved as:

Here are some cases where the support of expressions is particularly useful:

  • To centralize common configuration for sets of requests into context variables, like hosts and content types
  • To use response elements from other requests
  • To set expectations on responses thanks to assertions

The following figure summarizes these different cases:

These are 3 use cases to help you get started using expressions to test your APIs:

  • Request parameterization – Leverage context variables to send requests for different environments like staging or production.
  • Data manipulation – Leverage expressions to build request contents according to criteria or random contents.
  • Request chaining – Use parts of previous requests and responses to execute new ones. This allows users to implement complex test scenarios.

Request parameterization

If there is a variable named contentType in your selected context, you can use the expression ${"contentType"} anywhere to reference its value. When executing requests or evaluating assertions, the value will replace the expression.

Data manipulation

Generate data

Restlet Client comes with a set of predefined methods to generate data:

  • random: returns a random integer between 0 and a maximum;
  • timestamp: returns the timestamp of the current date;
  • uuid: creates a universally unique identifier;

Here’s an example a generated UUID:


Modify data

Other methods apply to a string object:

  • md5: creates the MD5 hash for a string
  • base64: encodes a string using Base64 encoding. This method is particularly useful if you want to define the value for HTTP basic authentication.
  • string: returns a value as a quoted string. This is particularly useful in the context of JSON.
  • substring: returns a substring according to start and end indexes;
  • hmac: creates a HMAC for a string based on a cipher and a secret key;
  • lower: converts all characters of a string to lowercase;
  • upper: converts all characters of a string to uppercase;

Here is a sample to create the content of the Authorization header in the context of an HTTP basic authentication:


Let’s now tackle the way to reference elements into both requests and responses and to chain requests.

Chaining requests

Through expressions, Restlet Client gives you access to any element in the request’s repository. Referencing elements isare based on names potentiallyeventually including container names (projects, services, and scenarios). For example, to reference a request definition contained in a scenario within a project, we can use this expression:

${"<project name>"."<scenario name>"."<request name>"}

This returns the following structure:

  name: "request name",
  request: {
    uri: {string},
    method: {string},
    headers: {object},
    body: {string or object}
  response: {
    status: {
      message: {string},
      code: {number}
    headers: {object},
    body: {string or object}

Note that the elements into the response property correspond to the response of the last executed response. The headers names are lowercased.

For example, to get the status code of the last execution of the request named “request1”, just use the following expression:

${"my project"."my scenario"."request1"."response"."status"."code"}

Restlet Client allows users to reference elements with request and response elements but also in elements from the contents. This is supported with XML contents via XPath and JSON contents via JSON path and makes it possible to leverage elements from previous requests to build new ones – i.e. use the id of a newly created element from the response of the creation request then check that it is gettable with another request.

Such an approach is particularly useful within scenarios to craft a sequence of requests. If you want to learn more about these capabilities, you will find more detailed information in this article.

JSON content

Restlet Client includes native support for JSON, but you can also get specific parts of a JSON document via JSON path. In the previous section, we missed the jsonPath method. It applies to a JSON object and returns a value according to a JSON path expression.

In fact, evaluating expressions to browse object graphs internally relies on the jsonPath method and provides some syntactic sugar.

The following expression (we used previously):

${"my project"."my scenario"."request1".response.status.code}

is equivalent to:

${"my project"."my scenario"."request1".jsonPath("$.response.status.code")}

You can note that there is no need to use the jsonPath method within assertions with type “JSON Body”. Restlet Client directly understands that JSON path expressions are used. The following figure provides a sample:

XML content

Restlet Client provides a similar support for XML based on the XPath syntax. In this case, no helper method is explicitly defined but this feature can be used in assertions with type “XML Body”.

To get the same element as in the JSON example but on an XML payload, the XPath is: /list/Company[1]/tags/tags[1]/text().

Tip: Indexes begin at value 1 in XPath 😉




    Thank you for the such a nice explanation.
    I’m trying to build a expression is the request from response of the another request.
    “approveRequest”: ${“Test”.”CreateRequest”.”response”.”body”.jsonPath(“$.CM-CreateRequest.requestId”)}.

    On expression builder i can see the value of the other request’s response element but when I submit the new request the value is not appending to the request and endup with an error “Request Id mising “.

    Please suggest. Appreciate your help.

    Thank you.

  • enickel

    Is there any way to apply a function to two variables at the same time?.

    An API requires in Authentication header the “username:password” in base64.
    I want to make it dynamic and I have expressions for the values or variables as ${“username”} and ${“password”}. But I can’t partially apply the function (e.g. ${“username”.base64()} ) and combine them.
    Is there any way to concatenate two variables and a string (“:”) and apply a function to the result?
    (e.g Something like ${${“username”}:${“password”}.base64()} )