18 November 2008 - 2.5 user guide blog eclipse intellij netbeans maven PDF files forums bugs sourceforge eviware.com


Eviware Logo

REST Parameters and Representations

Parameters and Representations a key concepts in a REST-style service; Parameters for parameterizing a resource and its access methods, Representations for defining how a Resource can be retreived and updated.

REST Parameters

Parameters can be defined on both resource/child-resource and request level and are managed via a parameters table in the corresponding Resource/Request editors:

The toolbar at the top of the table has the following actions: (left to right)

  • Add - adds a new parameter
  • Delete - prompts to delete the selected parameter
  • Clear - clears all current parameter values
  • Move Down - moves the selected parameter down one row in the table
  • Move Up - moves the selected parameter up one row in the table
  • Update from URL - prompts for an endpoint and adds/extracts corresponding parameters

Depending on a parameters Style in the above table, its value will be added to an outgoing request in different ways:

  • QUERY : added to the query string of the target URL upon submitting
  • HEADER : added as an HTTP Header to the outgoing request
  • TEMPLATE : replaces the corresponding {<parameter name>} placeholder in the URL path upon submitting
  • MATRIX : appends corresponding ";<parameter-name>:<parameter-value>" pairs to the URL path (before the query string) on submitting. If the parameter is defined as a Boolean, only the parameter name is added when its value is set to "true".

Furthermore, each parameter has a number of detailed settings that can be accessed via the "Details" tab below the parameter table;

The settings are as follows:

  • Required : if the parameter is required to have a value
  • Default : the default value to use
  • Type : the XML Schema Type of the parameter value
  • Options : a list of possible parameter values
  • Description : a descriptive text for the parameter
  • Disable Encoding : disables URL-Encoding of the parameter value when it is sent

These settings mainly affect two behaviours in soapUI:

  1. The generated WADL which contains all but the last setting
  2. The input field generated in the soapUI Pro Form Editor for the parameter:

As you can see above the generated form contains drop-downs, type-information, etc as configured for each parameter.

REST Representations

A REST request can both send or receive an arbitrary number of representations. In requests these correspond to the content of the message body (PUT or POST messages), in responses these correspond to the actual content of the response. Which actual representation returned of course depends on the actual resource implementation; from a strict HTTP-point-of-view, the HTTP Accept-Encoding header should be set in the request to let the resource "know" how it should return itself. A more common alternative is to have parameter in the request that specified the desired representation (as the "output" parameter in the parameters table above).

soapUI visualizes request and response representations with corresponding inspectors at the bottom of the request/response editors:

If the underlying resource has been imported from a WADL, this table will contain the representations defined therein, otherwise it will be empty. The columns are:

  • Type : the type of representation; for requests this will always be REQUEST, for responses this can be either RESPONSE or FAULT.
  • Media-Type : the mediaType of the representation
  • Status Codes : for response representation types only, this is a space-separated list of HTTP Status codes that together with the media type identify the representation.
  • QName : an optional QName corresponding to a global element in one of the XML Schemas in an imported WADL

Using the add/delete buttons in the toolbar allows one can add/remove representations as desired (to be used for validation and WADL generation). Selecting the Auto-Create option will make soapUI automatically create representations for each incoming response and outgoing request.


Next: REST Resources