Examine provides a simple but very effective REST testing support that can be used to test REST-based Web Services. The starting point for REST-testing is the REST project. A REST project is a collection of Resources where each resource represents a single HTTP endpoint accessible that can be invoked over a HTTP method like GET, POST, DELETE, PUT, etc. Each Resource can in turn contain sub-resources and acts as the parent of the sub-resource. The sub-resource itself is a valid REST Resource and the same rules that apply to resources also apply to sub-resources.
Consider the example of a REST-based sample Stock Quote Service that is available
at the endpoint: http://localhost:9998/stockquote. We'll use this as
the example to describe and demonstrate how to use the REST functionality going
forward.
To begin, create a new REST project from the Projects screen. Click on the link button to bring up the Create New Project dialog and select the option. Clicking on button brings up the REST resource creation dialog as shown below:
Specify a unique project name (e.g. SimpleStockQuote) and click on
to create the project. If the Add new
REST resource... checkbox is selected, then you can also create a
REST resource immediately following the REST project creation. This brings up
the Create new REST Resource dialog as shown below:
In the displayed dialog, specify the values of the following fields:
- Name
-
The name of the REST resource - this can be any logical name that represents this resource endpoint. This is a required field.
- Base URL
-
This field represents the base URL of the resource. For e.g. value can be
http://localhost:9998that specifies the protocol (HTTP/HTTPS), the server name (localhost) and the port number (9998). The base URL will be common to all sub-resources that are created as child resources of this resource. This is also a required field. - Resource URI
-
This field represents the actual context path of the resource. For e.g. in the dialog below, it is set to
/stockquoteand the final resource URL will behttp://localhost:9998/stockquote, which is a combination of the Base URL and the specified Resource URI.Note
It is also correct to specify the base URL itself as
http://localhost:9998/stockquoteand leave the Resource URI as/. In this case also the resource endpoint would be the same. However, subresources of this resource would inherit the complete Base URL with the 'stockquote' path segment - HTTP Method
-
This field represents the available HTTP methods that can be used to invoke this resource URL. The available methods are GET, POST, PUT, DELETE, OPTIONS, HEAD. It defaults to GET.
Once the REST project is created, clicking on the project name, displays the
project details like Created and Modified date. REST resources which are created
as direct children of the REST project are called 'root' resources. These
resources are represented by the
icon.
Root resources represent the top-level resource endpoints that can in turn contain many sub-resources under them. Each root resource contains a Base URL that captures the protocol, host and port information of the REST endpoint. To create a new root resource as a child of the REST project, right click on the REST project name and select as shown below:

This brings up the same Root Resource dialog to specify the resource details as shown in this figure . Clicking on the root resource node in the tree view displays the resource details like this:
The details view contains Main, Request and Test tabs that can be used to configure the current root resource. The response tab displays the result of invoking the resource endpoint.
The Main tab contains the following resource configuration fields:
- Base URL
-
This field represents the base URL of the resource. For e.g. value can be
http://localhost:9998that specifies the protocol (HTTP/HTTPS), the server name (localhost) and the port number (9998). The base URL will be common to all sub-resources that are created as child resources of this resource. This is also a required field.Note
The Base URL field is editable only for the Root Resource. Sub-resources will automatically inherit this value from their parent resource.
- Inherited Path
-
This is non-editable value that represents the path inherited by this resource from all its parent resource hierarchy. For root resources, this value will is empty (None).
- Resource URI
-
This field represents the actual context path of the resource. In this example, it is set to
/stockquoteand the final resource URL will behttp://localhost:9998/stockquote, which is a combination of the Base URL and the specified Resource URI.The button can be used to specify the values for any resource parameters specified as part of the resource URI. Please refer to this section on the different types of resource parameters for more information.
- HTTP Method
-
This field represents the available HTTP methods that can be used to invoke this resource URL. The available methods are GET, POST, PUT, DELETE, OPTIONS, HEAD. It defaults to GET.
- Content-Type
-
This field presents the available pre-defined content types that can be set when sending the request to the resource endpoint. The default set of values are as shown below.
If the content-type you would like to set is not available, you can click on the
button to add a new content type to the
list and select it. - Accept
-
The Accept field can be used to specify the value of the Accept HTTP header. By default, this value is */*, which means that there is no preference for the client in terms of the content type that the server should send the response in.
Subresources are resources that are created as children of a root resource or as children of other subresources. The subresource represents a REST endpoint whose request URI contains as part of its path, the URI of its parent resource.
For e.g. if a root resource contains a full request URI such as
http://localhost:8080/employees, then a possible
subresource URI would be of the form
http://localhost:8080/employees/john.doe. Here the
subresource request URI is /john.doe and it inherits the
/employee path from its parent resource.
Subresources are identified by the icon:
in the REST project tree view. To create a new
subresource, right click on either an existing root or subresource and
select Sub Resource as shown below:
Clicking on the subresource icon on tree view displays its details as shown below:
The subresource details view is similar to the root resource details, except that the Base URL field is disabled and its value is populated with the value from the parent resource. If the parent resource is also another subresource, then the value is got its parent and so on until a root resource is encountered.
Also, the Inherited Path field value is populated with the URI computed from the resource hierarchy leading up to this subresource. This path would be used as the prefix of the Resource URI value specified for this subresource.
REST resources can have different types of parameters that make up the data portion of the request. This data can be sent as part of the request in multiple ways to the resource endpoint. Following are some of the different resource parameters that can be configured:
Query parameters are field-value pairs that are sent as part of the
request URI query string. A typical URL containing a query string is as
follows:
http://server/path/resource_name?query_string.
The query string is the last portion on a request URL and is specified
after the ? character.
To specify query paramters for a resource, enter them in the Resource URI field as shown below:
In the figure above, the Resource URI value is
specified as quotes?symbol={sym}. The
?symbol={sym} part is the query string for this
resource endpoint.
The {sym} value is a placeholder for the actual data
that will be sent to the endpoint. This data can be entered by clicking
on the button, which brings
up the dialog as shown below:
Note
It is not required to enter the value of the field in the form
{name} and the value can be entered as part of
the resource URI itself. It is however easier to manage the
data that makes up the fields of the query if you use the form
field1={value1}&field2={value2} and then
specify the values in the Resource
Parameters dialog.
Important
Please note that if you have entered a placeholder in the resource URI then a value must be specified for that field, or there will be a runtime error when sending the request
Template parameters are parameters which are part of the request URI
path segment itself. The parameter is entered as {name}
anywhere on the request URI. An example of this shown below:
Here the resource URI value is set to
quotes/{symbol} where the parameter is
{symbol}. The value for symbol can be
entered by clicking on the
button.
Form parameters are name-value pairs that are usually submitted from a HTML Form. It is possible to send this kind of parameters to a HTTP endpoint when using a "write" HTTP operation like PUT or POST. The figure below shows a sample configuration for a resource endpoint that accepts form parameters:
To send form parameters to the resource endpoint, the following must be done:
-
Set the HTTP method either PUT or POST
-
Set the
Content-Typefield value to be eitherapplication/x-www-form-urlencodedormultipart/form-data. -
Add one or more form data through the Request->Form Data tab.
If the content-type value is multipart/form-data, then
the form values are sent as MIME multipart values in the request (as if
they were attachments).
If the content-type is application/x-www-form-urlencoded,
the entered form values are sent as name=value in the
request body.
Note
The Form Data tab under the
Request tab will be disabled if the
Content-Type value is not either
application/x-www-form-urlencoded or
multipart/form-data
Header parameters are nothing but HTTP request headers that are sent to the resource endpoint. Please see the section on configuring the HTTP request for more information on how to send custom HTTP headers.
Matrix parameters are request URI parameters that take the form
;name=value. They are similar in purpose to query
parameters but unlike query parameters can appear anywhere in the path
and don't necessarily have to be at the end of the URI. Below figure
shows how to create a subresource with a matrix resource parameter in
the request URI:
Here the ;currency={currency} part of the request
URI corresponds to the matrix parameter and is part of the path segment
that also contains the template parameter {symbol}
You can enter the values for the two parameters using the button
Other aspects of the HTTP request sent to the resource endpoint such as the HTTP headers, Authentication information or the SSL configuration if the endpoint is using the HTTPS protocol can be configured by clicking on the Request tab.
To send custom HTTP headers, click on the button to add a new row in the headers table and specify a value for the Name and Value fields.
Note
Only HTTP headers configured for the current resource will be sent in the request and any headers configured for the parent resource(s) are not sent
If the REST resource endpoint requires either HTTP Basic or Digest authentication, it can be configured through the Authentication tab as shown below:
Click on the checkbox to enable the username, password and related fields.
The checkbox if enabled results in the Authorization header being sent to the service even before the service challenges for the credentials.
The Authentication Type field can be either Basic or Digest and it results in the use of either HTTP Basic Authentication or HTTP Digest Authentication as outlined in the RFC 2617 (http://www.ietf.org/rfc/rfc2617.txt)
If the resource endpoint is accessible over HTTPS, then it is possible to specify the keystore and / or truststore to use for SSL key negotiation. To do this select the SSL tab under the Request tab as shown below:
Click on the checkbox to enable specifying a keystore and/or truststore to use.
The KeyStore and TrustStore drop-down boxes display all the available keystores in the system for the currently logged in user.
If SSL Client Authentication must be performed, then select the keystore that contains the private key whose equivalent public key is known to the service provider. To disable SSL Client Authentication, leave the KeyStore field empty.
To specify a custom truststore that contains the service provider’s X.509 certificate, select a truststore from the available stores. This truststore must contain the server certificate imported as a public key in it.
The field determines if the hostname specified in the X.509 certificate obtained during SSL handshake will be compared against the hostname of the endpoint to which the request is sent.
The ‘Refresh keystores’ button reloads all the available keystores and truststores.
To send attachments as part of the REST request to the resource endpoint,
the Content-Type value must be set to be either
mulitpart/mixed or multipart/form-data.
In the Request tab, select the Attachments tab to upload files that should be sent as attachments (MIME parts) in the request message.
Note
The buttons in the
Attachments tab will be disabled if the
content-type is not one of mulitpart/mixed or
multipart/form-data .
Clicking on the button brings up the dialog to upload a file from your local system to the server running Examine as shown below:
Click on button to select a local file and then click on to transmit the file to the Examine server. The uploaded file is stored in a user-specific attachments folder that is unique for each individual Examine user.
Once the file is uploaded successfully, it is displayed in the attachments
table. The content type of the file is determined automatically. The Content
ID column is empty by default and setting a value (which should be unique
for each attachment) here will set the Content-ID MIME
header.
Every REST resource details view includes the Test tab that be used to configure the test case for that particular resource. This is useful when you want to assert some information in the response coming back from the resource endpoint. This functionality is similar to configuring a test case for SOAP scenarios.
The Test tab allows for adding assertions that execute on the REST response and verify the assertion requirements. The available assertions can be seen clicking on the button as shown below:
The link can be used to associate this REST test case with an existing Test Suite or a new REST-only Test Suite.
Available Test Assertions
The default set of available Test Assertions for REST resources as follows:
- Assert HTTP Response Code:
-
This assertion verifies that the HTTP response code is a particular code such as 200 (OK) or 401 (Unauthorized)

- Assert HTTP Header:
-
This assertion can be used to check if a particular HTTP header is present, absent or is equal to a certain value.

- Assert HTTP Response time:
-
This assertion can be used to verify if the HTTP response was either less than or greater than a certain threshold value specified in milliseconds.

- Assert Response Contains:
-
This assertion can be used to check for the presence of a particular token in the HTTP response. If the ‘Regular Expression’ checkbox is checked, then the specified text is used a regex pattern against the REST response body. The regex pattern should follow the Java regular expression rules.

Tip
For more information on how to use Regular Expressions, please refer to this page: http://download.oracle.com/javase/tutorial/essential/regex/
- Assert XPath Result:
-
This assertion can be used to check if an XPath expression evaluates properly against the REST response (if it is XML). Click on the ‘Configure’ button to open the XPath Expression dialog box where you can enter the XPath expression to use and declare the namespace URIs for any prefixes used in the expression.

Each namespace declaration should be entered on a new line and is of the form:
prefix = URI
The result of evaluating the XPath expression will be a Boolean true/false. If the xpath expression results in DOM Nodes, then the result is True and if no there are matching nodes, the result is false. If the expression contains a predicate clause, then the result is either true/ false as well.
- Assert XML Schema:
-

This assertion can be used to perform XML Schema validation of the REST response body contents. This is only applicable if the response is in XML format. To add XML schemas against which the response should be validated, click on the button to open the XML Schema configuration dialog as shown below.

The button can be used to upload a single W3C schema (XSD) file or a zip file containing the root schema and its imports/includes as relative references within the same archive.
When the REST resource is executed, the assertions configured in the Test Case are verified against the response. The assertions that failed and succeeded are highlighted in red and green respectively as shown below:

















Contents
Search
