By gstachni-Oracle on Mar 04, 2015
Introduction to the REST Service Editor, Part 1
By Preston Appel
With the MAF 2.1 release, OEPE users can now easily develop applications that interact with REST APIs. All the tooling that has been added is available via the REST Service Editor. This editor allows the user to experiment with existing REST APIs and to describe their requests and related data types. This blog covers the basic functionality of the editor and its REST Client, REST API and Data Types pages, by showing how you can send a simple GET request to a server and then store a description of the request and of the received payload. Part 2 of this blog leverages this description to generate Java 8 code that consists of an API that can be used to send the request and to consume the received information programatically.
This blog assumes some knowledge of MAF development with OEPE. To create a REST service description that we’ll modify in our REST Service Editor, we need a MAF 2.1 application. Here is an outline of how to create it:
- From OEPE, click on File/New/MAF Application
- Enter the Application display name, confirm that the Runtime version is 2.1.0 and click Next
- Alter the project names and default packages as desired and click Next
- Add a deployment target, if necessary, and click Finish
- Click Yes to open the Oracle MAF Perspective, if prompted
Please refer to the documentation if you need further details.
Creating a REST Service Description
We can begin exploring REST services by creating a REST Service Description, an XMI file that
will be modified by our REST Service Editor. REST Service Descriptions can only be created in
the view project of a MAF 2.1 application. Below, we create this file by clicking the context
menu’s File/New/REST Service Description.
On the REST Service Description dialog, enter a new file name, if desired, and click Finish to
complete creation of the XMI file and open the REST Service Editor.
From the image below, you can see the first page of the REST Service Editor: REST Client.
The REST Client page is for experimenting with existing applications that expose REST APIs.
This page is not part of the persistent state of the REST Service Description, so changes neither
dirty the editor nor are they persisted when you save the editor.
Testing REST APIs with the REST Client Page
Now, let’s invoke a REST API. For the purposes of this blog, we have a simple resource that will
return a list of departments. We start by entering its URI in the Address field. Note that we’re
using a GET method.
Currently, the editor is geared toward JSON REST services, so we will need to get a JSON payload
if we want to import it to create data types. To do this, we modify the Request Details by adding
a header to indicate that the request will accept application/json payloads. We do this by clicking
the add icon on the Headers tab of the Request Details section. The Add Header dialog supports
The Headers can be edited, deleted or reordered.
After entering the method, address and header, we are ready to send our request. Click on the Send Request
button to get a response.
The status in the Response section indicates that we have successfully sent our request and
received a response back.
For the purposes of this blog, the more interesting view of the response is the Rendered Content. This will
give us a good idea of what data types will be created when we import this JSON payload.
We have received back a JSON object containing a JSON array called "departments." Within each department, we have an object (a department) with an id and an array called "employees." The employee object has departmentId, id and name attributes. While not shown, the last employee object also contains a manager object, which is just another employee (at least in our payload). There’s more information on how this payload is imported in the data types section near the end of this blog.
Importing the Request and Data Types
Now we’re ready to import the request and data types from what we have entered on the REST Client page of the editor. Importing this information will allow us to replay the same request in the future and also to generate useful artifacts (like Java code) from it.
To import the request and data types, click Import the REST Client Information at the top of the editor.
We can choose whether to import the request, the data types or both from the information on the REST Client
page. Since we want to describe both a REST API and the data types, we leave both checked and click the
We now have some choices about importing the request. First, we set up the root path. It is generally a
good practice to split the address up such that a new path is created for each of its segments. This tree
structure allows for requests on each of the path segments. In the Root Path field, we’ll break
"http://localhost:4545/departments" right after 4545 (by deleting "/departments") so that the
"http://localhost:4545" becomes the root path. The "departments" segment will then be created as a child
of the root path. In the Importing Revisited section, we’ll import
"http://localhost:4545/employees" so that you can further see how this works. We also supply a name for
the request, "getDepartments," and click Next.
Finally, we have some information about the data types that will be created. Note in the image below that
the box is checked to set the request output to a representation with the appropriate data type. This means
that our REST API will then know what data type to use for the data that is returned from the request. We now
click Finish to execute the import.
Describing the Request on the REST API Page
The import process takes us to the REST API page because we chose to import the Request. Looking at the Outline, we can see that our GET request, "getDepartments," was created and that it has the HTTP Header that we added to it: "Accept=application/json." Also note how a tree of paths was created from the root path and the "departments" segment.
Regarding the editor itself, the asterisk next to the file name at the top of the editor indicates that the
file is dirty. This operation has modified the XMI file. It is easy to back out changes, such as this import,
since the editor fully supports undo and redo.
Looking at the Output tab of the Request, we see that, as requested in the import wizard, we now have the
representation output appropriately set to Departments1 (the top level object from our JSON payload).
We’ll look at the data types in a moment, where we can change the name of Departments1 to something more
Probably the safest and fastest way to describe an existing REST API exposed by an application is to use
the import process that was just described above. However, new paths and requests can be manually added
to the REST API page or existing ones altered. If you do that, it is recommended that you use the Copy to
REST Client button, available on requests, so that you can test the work you have done.
Click on the Data Types tab to see how the JSON payload was imported.
Looking at the Departments data type, we see how the JSON payload below maps to what was created.
Departments is a complex type because it has attributes. The id and name are simple attributes, a json.Number and json.String respectively. The employees array has become a complex attribute of data type Employees (it’s plural because the name generator for the data types uses the array name "employees"). The manager type is also the complex type Employees.
Now, the data type Departments is plural for the same reason that the data type Employees is plural—
its name is generated from a name in the JSON payload which is plural. But the data type really does just
represent a single department. We can easily fix this by simply changing the name to Department. I’ve also
changed the name of the Employees data type to Employee since it also represents a single employee.
So where does the name Departments1 come from for the top-level JSON object in the payload? This comes from
the last segment of the address, which is "departments." The name generator had already used the name
"Departments," so "Departments1" is used here. Now that we’ve changed the data type Departments to
Department, let’s change Departments1 and save the description file. Also note that the Data Types page
tells you which requests use a particular data type.
As we’ve seen, we can manually alter data types by changing their names. We can also add attributes and new data types. But how does changing an imported data type affect subsequent imports of JSON payloads that use that same data type?
Let’s change the address to "http://localhost:4545/employees" on the REST Client page and send the request.
We’re still using the GET method and still have the "Accept=application/json" header. We get back a list
of employees as our JSON payload.
On importing the employee data, we will import both the request and the data types.
The import functionality recognizes that we already have the "http://localhost:4545" root path, so it
tells us it will just be creating the child "employees" path. We also provide a name for the request,
Finally, the import wizard tells us what data types it will be importing. Even though we previously
renamed the data type Employees to Employee (singular), the wizard sees that the Employees JSON object
is the same as (or similar to) the existing Employee data type and offers to use Employee rather than
creating a new Employees type, if the “Merge types into the existing matching domain types” box is
checked. (Employees1 in this case would come from the last segment of the address
"http://localhost:4545/employees" and is the top-most JSON object in the JSON payload.)
Here we see how we’ve continued to expand the tree of paths with the "employees" path. And remember that
each path can have its own requests.
Moving to the Data Types page, we see how the Employee (singular) data type from our previous import was
used and a new Employees1 data type has been created.
And to finish the work of describing data types for this blog, I’ve changed the name of Employees1 to Employees
and saved the editor.
Next Steps: Code Generation
We’ve now experimented with invoking an existing REST API through the REST Client page. That information has been imported to describe the REST API and its associated data types. In the future, we can use the REST Service Description we’ve created to replay the requests through the Copy to REST Client functionality. The description also serves to document the REST API.
Once we’re satisfied with our description of the REST API and the data types it uses, we can also generate Java code from it. That’s covered in Part 2 of this blog.