Understanding REST Parameters

NOTE: This page contains information for SoapUI Pro that has been replaced with Ready! API. To try enhanced REST testing functionality, feel free to download a SoapUI NG Pro trial from our website.

API Dojo

Also see the API Dojo article Understanding REST Parameters

1. REST Parameters

1.1. Watch the video tutorial

1.2. Resource Parameters

In this section we take a more detailed look at the different types of REST Parameters available to you in SoapUI. There are five types of parameters available: QUERY, HEADER, TEMPLATE, MATRIX and PLAIN.

REST Parameter Types

All parameters can be defined either at the RESOURCE level or at the METHOD level. Defining a parameter at the RESOURCE level means that it is inherited by all method nodes under it, and by all requests under the METHOD nodes. Defining it on the METHOD level only propagates the parameters to the requests; it does not affect the RESOURCE level.

Now, let’s have a look at different parameter types (except the PLAIN type which is ignored) to see how they can be used for parameterizing your resources.

1.3. QUERY Parameters

QUERY parameters are the most common type of parameter, which is appended to the path of the URL when submitting a request. You can see them added to the path after a ‘?’ in the path preview at the top of the REST Request editor:

REST Query Parameter

If you are simulating HTML Form submits, you might want to them to use the POST method instead. If we create a corresponding REST Method using the POST (or PUT) verb you will get an option to post query-parameters in the body instead:

REST Query Parameter with POST

As you can see selecting the option removes the parameter from the path, and if you submit and look in the Raw tab you will get:

REST Query Parameter with POST in Raw

As you can see the parameters have been added to the body of the message instead, with the corresponding Content-Length set accordingly.

1.4. HEADER parameters

HEADER parameters are instead added as HTTP Headers to the outgoing request. Let’s define one at the Method level:

REST Header param in a table

Setting a value and submitting the request gives the following in the Raw request tab:

REST Header param in Raw

1.5. TEMPLATE Parameters

TEMPLATE parameters are a flexible way of parameterizing the actual path of the request.  For instance, if you are using the FreeGeoIP REST API, which expects the IP address as part of the path, defining a TEMPLATE parameter for the address is quite handy:

REST add template param

Now we can just change this parameter to run queries using different IP addresses:

REST use template param

NOTE: TEMPLATE parameters really only make sense on the RESOURCE level. It is technically possible to have them on the METHOD level, but we don't recommend it. If you define a TEMPLATE parameter on the METHOD level, it will not be automatically appended to the resource path — you will have to manage it manually.

Finally, if we instead use the From view of the request (in soapUI Pro only), we can now see what the extra metadata added for the parameter is used for (besides for creating nicer WADLs):

REST template param in Form

Here the format is rendered as a drop-down with the "csv", “xml” and “json” options available.

1.6. MATRIX Parameters

MATRIX parameters are another way of defining parameters to be added to the actual path of the resource, but before the query string. They are not as common but never the less specified in the WADL spec and thus supported by soapUI. Add a MATRIX parameter to the weather method (as we did for the HEADER parameter above):

REST add matrix param

As you can see, the parameter is added to the path before the query string. Submitting the request now gives a 404 Not Found error from Yahoo Weather:

REST matrix param error response in raw

This is trustily added to the response representations for the method as a Fault Representation:

REST add fault representation