A REST Service contains any number of resources available on their corresponding path. Resources themselves can have as many levels of child resources as desired; a child resources path will be the concatenation of all its parents’ path with its own.
We’ll start with a new REST to make exemplifying a bit easier, start by creating a new REST Service in your project (from the Project Popup) for the Twitter Search API as follows:
Once created adding our first resource is straight forward; select the corresponding option from the REST Service popup menu:
Selecting this opens the following dialog:
Start by adding a name and the search URL above (http://search.twitter.com/search.json?q=soapui) now press the “Extract Params” button which will extract the Query parameters from the URL to the Parameters table and normalize the URL relative to the one of the defined Service:
As you can see the query parameter has been extracted as a standard QUERY parameter (more on parameters below), pressing OK now asks us to define a method for the Resource:
Rename it to “Simple Search” and press OK. Now we get the following in the navigator tree:
And the “Request 1” request window has been opened for you, submit the request with the top left green arrow and you will get:
Before digging in to the REST Request editor we need to back up a bit and look at the generated objects in our project. Let’s start by double-clicking the created Search resource, which will open the following window:
In the toolbar you can see and change the path that the resource is mapped to. Under it is a “Resource Parameters” tab in which we can see the “q” parameter extracted during the resource-creation process. Since it is defined at the Resource level, the parameter will be available for all child resources, methods and requests below the resource in the hierarchy. Use the toolbar at the top to manage parameters, selecting a parameter enables the fields at the bottom of the window which allow you to enter detailed information for the parameter.
This data can be specified for several purposes:
- For correct parameter definitions in the generated WADL (see below)
- For presenting a nicer in put Form in the Form editor for REST Requests (see below)
- For custom encoding handling when setting a parameter value (the “Disable Encoding” setting)
Let’s set the parameter to be required and add a nice description (as shown above), this will give a nicer WADL in the end (as you’ll see below).
Next in the REST Service hierarchy is the GET Method we defined for the resource (which is highlighted in the screenshot above). You can define any number of methods for a resource with the “New Method” option on the resource popup menu, which opens the same dialog we saw above when creating the initial method. Double-clicking the method opens its editor window:
The toolbar at the top allows you to change the HTTP Method to use (GET, POST, PUT, DELETE, OPTIONS and TRACE are supported) and the “Method Parameters” tab is similar to the “Resource Parameters” tab we saw above; parameters defined here are available for all requests created for the method. Since we defined our “q” parameter at the Resource level this table is empty and the corresponding detail fields at the bottom are disabled.
Specific for the Method window is the “Representations” tab:
Here you can see the representations defined for the method, in our case soapUI automatically generated a representation for the response we received when submitting our first request, and it will continue to add new representations for each unique response content-type and status-code received. Using the toolbar buttons you can add and remove representations as desired.
Tip: The defined Representations for a Method are also visible in the corresponding Representations tabs available in the REST Request/Response editors described below.
Generated WADLs
When defining a REST Service “manually” as we have done above, soapUI automatically generates a corresponding WADL for us. If you now double-click the original REST Service we defined for Twitter and select the WADL-Content tab, you will get the following:
Voila! A nicely defined and formatted WADL for the Twitter search API! Just as for a REST Service originating from a WADL we can now generate both code and documentation for the service as shown above.
One thing that is missing here is the XML Schema for the response messages returned by Twitter, and later on we’ll have a look at the Schema Inference functionality in soapUI that can generate this for you as well, based on the actual messages received from the service during testing.