Since December 2017, Application Express 5.2 Early Adopter 1 is available. One of the new features in APEX 5.2 will be declarative support for REST Services in Application Express components - that means, developers will be able to create a component, like an interactive report, directly on an external REST service. This tutorial walks you through that new feature, by creating some APEX pages reporting on the GitHub REST API. You can try these out on the Application Express Early Adopter instance.
Github provides a very comprehensive REST API in order to interact with the platform. Several API endpoints provide information about Github users, repositories, contributions and many more. The following screenshot is an example for this API: https://api.github.com/users/oracle/repos returns the list of repositories owned by the oracle organization. As with most REST APIs, the data comes as a JSON feed.
The goal is to have an Application Express page presenting that data - as follows:
The following steps explain how to achieve this. To begin, create your workspace on apexea.oracle.com (if not already done) and log in. Then create a simple application with just one home page (accept the defaults in the new Create Application wizard). One the application has been created, navigate to Shared Components and look for Web Source Modules into the lower left corner.
The Web Source Modules section is new in Application Express 5.2; all meta data for external REST services is being configured there. Within Web Source Modules click on the Create button in order to begin working with the Github REST API. Since we are at the very beginning, create your first Web Source Module from Scratch.
In the next dialog a name and the URL endpoint of the REST Service is needed. Use the following data, then click the Next button.
The next step will split up the endpoint URL into a server-specific and a service-specific part. With the server-specific part, Application Express will create a new Remote Server object. That additional entity allows to group REST endpoints pointing to the same server. When, for such a collection of REST services, the server changes, it will be sufficient just to adjust the Remote Server object. APEX does a proposal how to split the URL - however, for Github, we want to adjust this:
The next wizard step is about Authentication. The Github API does not require authentication, so simply click the Discover button in order to have Application Express invoke the REST endpoint.
Application Express will now invoke the REST endpoint, grab the response data and examine the data structures. The following wizard step shows the results of that discovery. Application Express displays the column it has found (and their data types) and a preview on the parsed response data.
The More Detail button opens additional tabs, showing HTTP response headers and the raw JSON response. When satisfied, click the Create Web Source button, in order to store the discovered meta data into Application Express. You will see the Web Source Modules section containing one new entry for the Github Repositories REST endpoint.
Next, we are about to use the new Web Source Module within an APEX component. Navigate to the application pages and click the Create Page button in order to add a new page. Choose a Report page and use the Classic Report implementation (Application Express 5.2 will support Classic and Interactive Reports based on Web Source Modules).
In the following steps, provide a name for your new page and choose whether to add an entry to the navigation bar on the left hand side of your application. The interesting part will be the last step of the wizard, where the data source for the report will be configured.
Starting with 5.2, Application Express exposes the new Data Source attribute. Local Database creates a report on top of data in the local database (as for all the releases before). REST Enabled SQL is discussed in a separate blog posting. Web Source Modules allows to reference the REST service meta data, we just have created within Shared Components.
Choose Web Source and pick Github Repositories in the second Web Source Module select list. Then the Columns shuttle will populate with about 90 columns (the Github REST API returns a lot of attributes). Choose an interesting selection; make sure to add at least, but not only the ID, NAME, CREATED_AT, UPDATED_AT and AVATAR_URL columns to your report. When finished, click Create.
In Page Designer, you'll see your new report as part of the page. Run the page to see your first result.
Time to adjust the layout of this report a bit. The AVATAR_URL is pointing to an avatar image of the repository owner. So, in Page Designer, navigate to that column and simple apply the <img> tag using the HTML Expression attribute.
Provide some nice format masks for the CREATED_AT and UPDATED_AT columns, adjust the column order to your needs and hide columns you don't want to see. After some of these adjustments, your page might look as follows:
So far we have, very easily, created an APEX page reporting on an external REST service. But the oracle user is actually hard-coded in our Web Source Module. Now, we want to change that: The report should be able to report on any Github user we want.
For that, we first need to add a Web Source Parameter to the meta data in Shared Components. Thus navigate to Web Source Modules within Shared Components and then to the details of the Github Repositories module.
Navigate to the Module Parameters tab ... and click the Add Parameter button.
The Github API requires the user name to be a part of the URL. So, the user/oracle/repos path lists the repositories of the "oracle" user, users/dani3lsun/repos would list the repositories of one of the very active APEX community members. So add the new parameter as follows:
Click on Add Parameter, when finished.
Next, we have to change the URL endpoint of the Web Source Module in order to pick up the parameter. Click on the Web Source Module tab (this contains general information). Then change the URL Path Prefix of the Web Source Module from users/oracle/repos to users/:username/repos.
Finally, click the Apply Changes button. Then, head back to your page containing the report. We want to have a text field on the page, where the end user enters a Github user name. Then the report is supposed to refresh with the data for that very user. Thus, in Page Designer, add a new region above the report, add a page item (Text Field) and configure its layout.
Then review the Classic Report node in the tree on the left again. It now has an additional Parameters child node; there you'll find the username parameter you have configured. It still uses the default value configured in Shared Components. Change it to use the text field Item.
Add the item to the report's Items To Submit region attribute as well.
Finally save everything and run the page. With the oracle user name, everything looks still as before ...
When changing it to dani3lsun, the report will show another list of repositories.
That's it for now. Play a bit around with these features and settings. In the next posting, we'll create another component on another REST service and link the two together - as we did all the years before with normal tables.
And don't forget to provide your valuable feedback.