Restlet Blog

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 DHC offers a powerful feature: expressions.

First, let’s introduce what expressions are in DHC 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 DHC.

When the request above is launched, the URL will be resolved as: https://contactsapi.apispark.net/v1/companies.

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

DHC 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:

${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:

${"a20e6aca-ee83-44bc-80:c199f9c8-0548-4be7-965".base64()}

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

Chaining requests

Through expressions, DHC 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"}

DHC 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

DHC 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”. DHC directly understands that JSON path expressions are used. The following figure provides a sample:

XML content

DHC 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 😉

Leave a Reply

Your email address will not be published. Required fields are marked *