09 July 2009 - 3.0 user guide eclipse intellij netbeans maven download nightly forum bugs blog sf.net eviware


Eviware Logo

REST Services in soapUI

soapUI 2.5 introduces extensive possibilities to invoke and test REST/HTTP services, either starting from a WADL definition or just plain URLs. The REST/HTTP support is divided into two parts:

  • A new REST Service / Resource / Method / Request model in the Navigator with corresponding editor windows/popups/etc
  • REST-specific TestSteps for integrating REST testing with existing test-functionality

Mocking of REST services is currently only supported via the possibility to specify a document root for serving static content, an upcoming release will have full REST Service mocking functionality.

The REST Model

The model for REST Services in soapUI is closely modeled after the WADL model but does not explicitely require a WADL definition. If a REST Services is defined "manually" (without a WADL), the corresponding WADL will be automatically generated and can be used for validation, code-generation, etc.

REST Services in soapUI consist of the following key items:

  • Services - corresponds to Interfaces for WSDL, in a WADL this corresponds to the root application element. A Service contains an arbitrary number of heirarchically organized resources.
  • Resources - defines an addressable (URI) item that can be parameterized using a number of parameter mechanisms. Resources are created/modified/deleted using standard HTTP methods (PUT,POST,GET,etc) and can be made available in any number of representations (ie states), for example XML, JSON, PDF, etc. Also, resource can contain child resources which will inherit parameter and path information from their parent(s).
  • Methods - A resource in WADL/REST is accessed through a number of Methods. A Method is defined by it's HTTP method, Headers and parameters. The response is usually a representation of the invoked resource.
  • Requests - A Request is an instance of a request for a Method. Resources and Methods define Parameters by name and possibly default values, whereas Requests instantiate these with values.
  • Parameters - can be defined on both the Resource and Method level, see more below.
  • Representations - are used to define the content of a request or response, see more below.

A soapUI project can contain any number of both REST and WSDL services, allowing for integrated testing of corresponding services.

WADL Support

soapUI supports WADL in two ways:

  1. When defining a new REST Service one can do so from a WADL file/URL, which will import all defined resources and methods. Associated XML Schemas are also imported and used for validations and form-generation in soapUI Pro.
  2. When defining a new REST Service without a WADL by "manually" specifying endpoints, paths, parameters, etc soapUI automatically generates a WADL from these configured items.

In either case, the WADL can be used for code and documentation generation from the WADL Content tab in the WADL Service window (see below). Also, defined representations will be used to validate response messages when adding SchemaAssertions to REST TestRequest steps.

Creating REST Services

REST Services can be created in several ways.

  • From a WADL:
    • By specifying a WADL file or URL in the New Project wizard
    • By selecting the "Add WADL" popup menu option from the Project popup
  • Manually:
    • By selecting the "Add REST Service" option in the New Project Wizard
    • Via the "Add REST Service" option from Project Popup

When specifying a WADL, soapUI will read the WADL and create the corresponding model items in the project. When creating the service manually, the following dialog will be shown:

The following options are available:

  • Service Name (required) : an arbitrary name for the service
  • Service Endpoint : an initial endpoint for the service.
  • Extract Resource/Params : will open a dialog for defining an initial Resource and its parameters from the specified endpoint.
  • Create Resource : if no endpoint has been specified or "Extract..." has not been selected, this option will open a dialog to create an initial Resource.

The resource-related options are covered in more detail in Resources.

Service Properties and Action

Once created, the REST Service has the following properties in the bottom left:

  • Name - the name of the REST Service
  • Description - a short description of the service
  • Base Path - the base path to prepend to all resource paths when sending requests
  • WADL - the URL to the originally imported WADL (if available)
  • Generated - true if the WADL has been generated instead of imported

Right-click a REST Service in the navigator opens a popup with the following actions:

  • Show Service Viewer - Opens the Service Viewer described below
  • Generate TestSuite - Opens a dialog for generating a TestSuite for the service (see below)
  • Create Documentation - Prompts to generate HTML documentation for the REST Service which will be opened in an external browser
  • WADL2Java - Prompts to run the Wadl2Java tool for generating java classes for the services WADL (see below)
  • Export WADL - Prompts to export the WADL and included schemas to the file system
  • New Resource - Prompts to create a new Resource in this service
  • Delete - Prompts to delete this service
  • Online Help - Opens this page in an external browser

REST Service Viewer

Double-clicking a REST Service opens the REST Service Viewer which is basically layed out as the corresponding WSDL Interface viewer:

  • An "Overview" tab showing basic information about the WADL
  • A "Service Endpoints" tab allowing for management of service endpoints and default authentication settings.
  • A "WADL Content" tab displaying the WADL and its references XML-Schemas.

The toolbar for this tab contains the following actions (left to right):

  • Back - navigates back in the content tree
  • Forward - navigates forward in the content tree
  • Generate Documentation - prompts to generate HTML documentation for this WADL
  • Export WADL - prompts to export the WADL and referenced schemas to a local folder
  • Recreate WADL (not shown in screenshot) - for generated WADLs, regenerates the WADL from the defined REST artifacts.

Generate TestSuite

The "Generate TestSuite" option on the REST Service popup opens the following dialog:

The options available are:

  • TestSuite : target TestSuite or option to create a new one
  • Style : how to generate TestCases
  • Resources : a "flattened" list of all resources in the Service
  • Generate LoadTest : if a default LoadTest is to be created for each generated TestCase

Pressing OK will generate one REST RequestStep for each selected Resource, either all in one TestCase or in one TestCase for each.

WADL2Java Integration

soapUI integrates with the wadl2Java tool included in the WADL toolkit allowing one to generate java code from both imported and generated WADLs. Selecting the WADL2Java option on the REST Service popup opens the following dialog:

The options in the dialog correspond to those for the tool, once the path to wadl2java has been set in the global tool integration settings and the dialog has been configured as desired, pressing OK will launch the tool to generate the corresponding Java classes:


Next: REST Parameters and Representations