This topic explains how to configure and apply the REST Client tool, which sends messages to RESTful services. Messages can be sent with HTTP GET, POST, OPTIONS, HEAD, PUT, DELETE, TRACE, or custom methods. You can use REST Client tools in SOAtest and Virtualize.
Sections include:
The REST Client tool was redesigned in version 9.8 to facilitate the configuration process and provide additional flexibility.
REST Client tools created in versions 9.7.x and earlier will be automatically updated to use the new format when you open and save the associated .tst or .pvn in the current version of the product.
During the automated migration process, settings from legacy input modes are mapped to the new input modes. The legacy REST Client had Form, Literal, and Scripted input modes.
The current REST Client has constrained (OpenAPI/Swagger, RAML, WADL) and unconstrained service definition modes.
Migration is performed as follows:
Exact mappings are not available in the following cases:
When a tool with these unsupported mappings is migrated, details will be printed to the console.
When a legacy tool with unsupported mappings is executed, the tool will fail with a Quality Task outlining the mapping issues.
In the Resource tab, you specify the resource to which you want to send messages. The default service definition mode (unconstrained) allows you to specify a URL and query for accessing the service. If a service definition (OpenAPI/Swagger, RAML, WADL) is available, you can change to one of the constrained configuration modes.
Most of the available controls will vary depending on what you have set for the Service Definition field:
Parameters can be configured in the Path and Query tabs, as described in Parameter Configuration.
Unconstrained mode (the mode enabled when Service Definition is set to None) lets you specify the URL as a literal string, which can be either a fixed value, parameterized value, or scripted value. In addition, the method to invoke can also be specified as a fixed value, parameterized value, or scripted value. For details about
For details about parameterizing values, see the following chapters:
With fixed values, you can access data source values using ${var_name} syntax. You can also use the environment variables that you have specified. For details about environments, see Configuring Testing in Different Environments or Configuring Virtualize Environments.If the URL uses environment variables, the Resolved URL field will display how they resolve into an actual URL.
If the environment variable has been masked, however, the Resolved URL field will not show the actual value (also see Masking a Variable Value).
Parameters can be configured in the Path and Query tabs, as described in Parameter Configuration. Any changes made in the URL will automatically be propagated to the Path/Query table. Also, the URL will automatically be updated to reflect any changes made to the Path/Query table.
RAML configuration mode lets you specify the various URL components as follows:
var_name is a data source column, a URL of http://${HOST}:${PORT}/some/url/${var_name} might result in a Resolved URL of http://localhost:8080/some/url/${var_name}
You can set the Base URL field to use constrained (from the specified RAML URL), fixed (modifiable), or scripted inputs.
For details about scripting values, see Extensibility and Scripting Basics.
With fixed values, you can access data source values using ${var_name} syntax. You can also use the environment variables that you have specified. For details about environments, see Configuring Testing in Different Environments or Configuring Virtualize Environments.
Parameters can be configured in the Path and Query tabs, as described in Parameter Configuration. The URL will automatically be updated to reflect any changes made to the Path/Query table.
OpenAPI/Swagger configuration mode lets you specify the various URL components as follows:
var_name is a data source column, a URL of http://${HOST}:${PORT}/some/url/${var_name} might result in a Resolved URL of http://localhost:8080/some/url/${var_name}
You can set the Base URL field to use constrained (from the specified OpenAPI/Swagger URL), fixed (modifiable), or scripted inputs.
For details about scripting values, see Extensibility and Scripting Basics.
With fixed values, you can access data source values using ${var_name} syntax. You can also use the environment variables that you have specified. For details about environments, see Configuring Testing in Different Environments or Configuring Virtualize Environments.
Parameters can be configured in the Path and Query tabs, as described in Parameter Configuration. The URL will automatically be updated to reflect any changes made to the Path/Query table.
WADL configuration mode lets you specify the various URL components as follows:
var_name is a data source column, a URL of http://${HOST}:${PORT}/some/url/${var_name} might result in a Resolved URL of http://localhost:8080/some/url/${var_name}
You can set the Base URL field to use constrained (from the specified OpenAPI/Swagger URL), fixed (modifiable), or scripted inputs.
For details about scripting values, see Extensibility and Scripting Basics.
With fixed values, you can access data source values using ${var_name} syntax. You can also use the environment variables that you have specified. For details about environments, see Configuring Testing in Different Environments or Configuring Virtualize Environments.
Parameters can be configured in the Path and Query tabs, as described in Parameter Configuration. The URL will automatically be updated to reflect any changes made to the Path/Query table.
If you switch from a constrained mode (Service Definition set to RAML, OpenAPI/Swagger, or WADL) to unconstrained mode (Service Definition set to None), you will have the option of automatically populating the unconstrained view with values from the constrained view. The following example contains several configurations that be automatically populated after switching modes:
Switch the mode and confirm that you want to populate the client configuration values using the values from the service definition.
The client will be updated after confirming to override the service definition configurations:
In all modes (constrained and unconstrained), parameters can be configured in the Path and Query tabs.
The Paths tab lets you configure template parameters for the currently selected operation. For example, a path of "/parabank/services/bank/accounts/{accountId}" has a single path parameter: "accountId". In the unconstrained mode, parameters can be fixed, parameterized, or scripted.
In the constrained modes, parameters can be fixed, parameterized, automatically generated, or scripted.
The Query tab lets you configure the URL query parameters for the currently selected operation.
In unconstrained mode, parameters can be fixed, parameterized, or scripted. In the constrained modes, parameters can be fixed, parameterized, automatically generated, or scripted.
You can opt to append an equals sign (=) to query parameters with empty values. You will only see the equals sign in the URL preview when the parameter is fixed; when it is parameterized or scripted, the equals sign will be added when the test is run. This option is disabled by default.
Encoding Note
URL query parameters are formatted according to the "application/x-www-form-urlencoded" content type. Space characters are replaced with '+'. Non-alphanumeric characters are replaced with a percent sign followed by two hexadecimal digits representing the character code. Names and values are separated by '=' and name-value pairs are separated by '&'.
If you want to use a different format, query parameters can also be specified directly at the end of the tool’s endpoint URL (instead of in the Query Parameters section). For example, the following could also be specified as http://host:8080/path?a=1&b=2&c=3
Matrix parameters can be configured by appending them directly to the end of the last path segment in the resource URL. For example, the following parameter could also be specified as http://host:8080/path;jsessionid=12345
If the method you are using sends data (e.g., PUT, POST, DELETE), the Payload tab allows you to specify the payload for the message that will be sent.
Before you specify the payload itself, ensure that the appropriate payload format and media type are selected (in the Payload Format and Content-Type boxes). If the service definition is set to RAML, OpenAPI/Swagger, or WADL in the Resource tab, the payload format and content type here will be constrained to that URL and the selected resources.
These two settings control the Content-Type HTTP header and determine the available input modes. For example, the Form JSON view will only be available for JSON media types; the Form XML view will only be available for XML media types. If the media type is "application/x-www-form-urlencoded" and the service definition defines representation parameters for the currently-selected operation, then a Form Input view will be available to configure the parameters. This is similar to the Form Input used on the Path and Query tabs.
When specifying the payload, you can select input modes from the Input Mode drop-down list. The REST Client tool shares Input Mode options with other client tools. For more information on these shared options, see Input Modes.
For XML or JSON associated with a schema, the applicable form view will be automatically populated according to the values in the definition and editing will be restricted to ensure that the message complies with the specified schema. For instance, you will not be able to insert, delete, rename, copy, or paste tree nodes.
The HTTP options allow you to determine which protocol (HTTP 1.0 or 1.1) is used to send the request, as well as various options related to the protocol (security, headers, cookies, etc.).
Select the appropriate protocol from the Transport drop-down list, then configure its properties, which are described in the following sections:
SOAtest
Virtualize
Clients chained to responders can route messages to virtual assets on the local server without consuming an HTTP connection by using localhost, 127.0.0.1, or the special host name host.virt.internal. When using localhost or 127.0.0.1, the specified port must match the port Virtualize is deployed on; when using host.virt.internal the port is not used. For example, a virtual asset deployed on http://localhost:9080/myVirtualAsset can also be reached by a chained client using http://host.virt.internal/myVirtualAsset.
The following options are available in the Misc tab of the REST Client tool:
"302, 500-599", a 302 code or any code in the 5xx range will be accepted. If you're using a parameterized value, be sure that the value in the data source uses this same format (e.g., "302, 500-599").Timeout after (milliseconds): Specifies the length of delay (in milliseconds) after which your FTP, telnet, or HTTP requests should time out. The Default setting corresponds to the timeout set in the Preferences panel. The Custom setting allows you to enter a timeout. A non-positive timeout value can be entered to specify an infinite timeout.
Outgoing Message Encoding: Choose Custom from the drop-down menu and choose an encoding for the outgoing message. The default is to use the encoding configured in the immediate parent test suite (see Specifying Client Options). You can also specify this option globally in the Parasoft Preferences Misc settings (see Additional Preference Settings ).
The following tutorial lesson demonstrates how to use this tool: