REST Projects

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.

Creating a new project

To begin, create a new REST project from the Projects screen. Click on the New Projectlink button to bring up the Create New Project dialog and select the REST option. Clicking on OK button brings up the REST resource creation dialog as shown below:

Figure 6.38. REST Project - Create New Project

REST Project - Create New Project


Specify a unique project name (e.g. SimpleStockQuote) and click on OK 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:

Figure 6.39. REST Project - Creating a REST resource

REST Project - Creating a REST resource


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:9998 that 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 /stockquote and the final resource URL will be http://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/stockquote and 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.

REST Resources

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

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 Root Resource 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:

Figure 6.40. REST - Root Resource Details

REST - Root Resource Details


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:9998 that 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 /stockquote and the final resource URL will be http://localhost:9998/stockquote, which is a combination of the Base URL and the specified Resource URI.

The Resource Parameters 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.

Figure 6.41. REST - Default resource content types

REST - Default resource content types


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

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:

Figure 6.42. REST - Creating a REST Subresource

REST - Creating a REST Subresource


Clicking on the subresource icon on tree view displays its details as shown below:

Figure 6.43. REST - Subresource details view

REST - Subresource details view


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.

Resource parameters

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

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:

Figure 6.44. REST - Resource query parameters

REST - Resource query parameters


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 Resource Parameters button, which brings up the dialog as shown below:

Figure 6.45. REST - Resource parameters dialog

REST - Resource parameters dialog


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

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:

Figure 6.46. REST - Resource template parameters

REST - Resource template parameters


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 Resource Parameters button.

Form parameters

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:

Figure 6.47. REST - Form parameter configuration

REST - Form parameter configuration


To send form parameters to the resource endpoint, the following must be done:

  • Set the HTTP method either PUT or POST

  • Set the Content-Type field value to be either application/x-www-form-urlencoded or multipart/form-data.

  • Add one or more form data through the Request->Form Data tab.

    Figure 6.48. REST - Form parameter values

    REST - Form parameter values


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

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

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:

Figure 6.49. REST - Matrix parameters example

REST - Matrix parameters example


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 Resource Parameters button

Configuring HTTP request

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.

HTTP Headers

To send custom HTTP headers, click on the Add 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

Request Authentication

If the REST resource endpoint requires either HTTP Basic or Digest authentication, it can be configured through the Authentication tab as shown below:

Figure 6.50. REST - Request authentication

REST - Request authentication


Click on the Enable HTTP Auth checkbox to enable the username, password and related fields.  

The Do Preemptive Authentication 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)

SSL configuration

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:

Figure 6.51. REST - Request SSL configuration

REST - Request SSL configuration


 

Click on the Enable SSL 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 Verify Hostname 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.

Sending Attachments

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 Add/Delete 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 Add button brings up the dialog to upload a file from your local system to the server running Examine as shown below:

Figure 6.52. REST - Request attachment upload dialog

REST - Request attachment upload dialog


Click on Choose File button to select a local file and then click on Upload 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.

Configuring REST test case

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 Add button as shown below:

Figure 6.53. REST - Resource test case assertions

REST - Resource test case assertions


The Add to Suite 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 Configure button to open the XML Schema configuration dialog as shown below.

The Add 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:

Figure 6.54. REST resource test case assertions result

REST resource test case assertions result