By Greg Stachnick-Oracle on Mar 18, 2015
REST Service Editor Query Parameters
By Preston Appel
This blog covers how to specify query parameters using the REST Service Editor. As you will see, it is possible to set the scope of the query parameters to every request of a given URI or to just a single request. We will also review how to modify the output representation to only contain certain attributes. (This is also covered in the Modeling a POST Request and Redirection in the REST Service Editor blog.)
Background of Our REST API Model
In previous blogs (Introduction
to the REST Service Editor, Part 1 and Modeling a POST Request
and Redirection in the REST Service Editor), we described a REST API that had been exposed by an
application. This is shown below on the REST API page of the REST Service Editor.
Based on the documentation of the existing REST API that we are describing, we know that we can pass the query "verbose=false" to our GET request for departments. In this case, the response's JSON payload will just contain a summary description of each department. Usually, when we send a GET request to "http://localhost:4545/deparments," it returns multiple departments, where each department has an id, name, optional manager and an array of employees. When the query "verbose=false" is added to that URI, the JSON payload in the response will just contain the id and name of the department. How might we model this?
Modeling a Query on the Path
Let's say that we want to model this by adding the query to the "departments" path. (In this case,
we don't actually want to do this, but we’ll get to that in a moment.) First, remember that the
"departments" path is a child of the root path "http://localhost:4545." Since the paths will be
combined into the address "http://localhost:4545/departments," we are just altering the address
to include a query. We could just type the query at the end of the "departments" path, but to
ensure we have the correct syntax (and to encode any illegal characters), we will use the Compose
Address button to do this work.
Upon clicking the Compose Address button, we'll add the query "verbose=false" to the departments path.
We have now altered the "departments" path to contain the query.
Now, if we had a case where the query should apply to all the requests under the path,
then we could model it this way. However, we don't want the query "verbose=false" to
apply to our "createDepartment" request. To see that it applies to all requests—even
those we don’t want affected—select "(POST) createDepartment" and look at the
status line at the bottom of OEPE. The status line indicates the address that will be
used for the request.
Let's back out this change. We can either type control-Z, or click Edit/Undo Set 'Value.'
Modeling Query Parameters on a Request
At this point, we'll create a new request "getDeptSummaries" on which we'll set a query
parameter. To do so, we'll right-click on the Requests folder under the "departments"
path and select New/Request.
Enter "getDeptSummaries" in the Name field of the request (leave the Method as GET).
We also enter the HTTP Header "Accept=application/json" but I haven’t shown this step.
See Modeling a POST Request and Redirection in the REST Service
Editor, if you need help with this. It's very similar to how we'll add a query parameter.
To add "verbose=false," click the Add button on the Query Parameter tab of the Request.
Enter the name and value in the Add Query Parameter dialog.
We've now set up the query parameter for the request.
At this point, we can easily see what address will be used for each request.
With "(GET) getDeptSummaries" selected in the Outline on the REST API page,
the status line is "Address: http://localhost:4545/departments?verbose=false."
With "(GET) getDepartments" selected in the Outline, the status line is simply
Now, it just remains to set up the output.
Being Precise About Output
For our "getDeptSummaries" request, we want to model that the response will only
contain a summary of the information from the departments. To set this up, we
click on the Request's Output tab and select Representation for the Type field.
This is so we can specify the Output that will be returned in the response.
Click the Add button to set up the Representation. In this case, we will be returning
Department objects, so we select this for the Data Type. Since there will be more
than one department, we check the Multiple box. Finally, since our documentation tells
us that the query parameter "verbose=false" will result in returning just a summary of
the department information—specifically, the id and name attributes for each
department—we uncheck All attributes and select the id and name attributes.
We now have described our "getDeptSummaries" request with some precision.
With this model we can now, for example, generate Java 8 code, which will allow us to programmatically send our "getDeptSummaries" request. The generated code will know how to return just the department summaries due to how we modeled the output representation.