API Management is a hot topic these days. Back in September, Oracle announced the availability of the Oracle SOA and API Manager Cloud Services. This article will give you an introduction to the latter. If you have an Oracle SOA Cloud Service subscription or an local installation of Oracle API Manager, you can follow along.
For the purpose on this introduction I’m going to start with a Hello World SOAP based web service and use Service Bus to expose the service with a REST interface.
This article will look at API Management from the perspective 0f 3 personas: an API Developer (or curator), an API Admin and an API Consumer. These roles are described with more detail in Understanding User Roles in Oracle API Manager.
We will begin as the API Developer and publish an API to the API Manager. One job of the API developer is to shape or curate the APIs into a form that is potentially more consumable then those provided directly by the source application. One example of this could be to provide a simple interface to a complex ERP API. In this simple example, I will be converting a SOAP based web service into a more mobile friendly REST based web service.
After the API is developed, we will assume to the role of an API Admin and create users that are allowed to consume my APIs.
We will then assume the role of an of an API Consumer. This user is developing an application and would like to consume the hello world API provided by the API Developer.
We will conclude as the API Admin, looking at subscription and performance metrics.
An API Manager Cloud Service Instance has been provisioned. Alternatively, these instructions will also work with the on-premises version of Oracle API Manager.
Persona 1 – API Developer
We already have an API which we want to shape and virtualize using Oracle Service Bus. For this exercise, we will be exposing a SOAP based web service as REST.
Step 1 – Create a Service Bus Application and Import WSDL
Using JDeveloper 12.1.3, create a new Service Bus Application with Service Bus Project. I’ll call the application HelloWorldApp and the project HelloWorld.
Create a new a folder for the WSDL file:
Right-click the WSDLs folder and select Import and then Service Bus Resources:
In Step 1 of the wizard, select Resources from URL:
Click Next, ensure the Resource Type is WSDL and paste the following into the Source URL field: http://220.127.116.11/soa-infra/services/default/HelloWorld-XYZ/helloworldbpelprocessxyz_client_ep?WSDL.
Click Next and then Finish:
Step 2 – Create Business and Proxy Pipeline Services
Open the HelloWorld Service Bus Overview and drag an HTTP Technology adapter into the External Services lane to create a business service. Name the service HelloWorldBS and leave the Transport as http:
Advance to the next page of the wizard, set the Service Type to WSDL-based service and click the Browse WSDLs icon. Select the WSDL we just imported:
Click Next and Finish.
Drag a Pipeline into the Pipelines/Split Joins swim lane and set the Service Name to HelloWorldPP:
Click Next and set the Service Type to the same WSDL we used for the Business Service. Deselect the option to Expose as a Proxy Service.
Click Finish and wire the HelloWorldPP to the HelloWorldBS:
Step 3 – Expose as Rest
Right-click the HelloWorldPP and select Expose As REST to launch the Create REST binding wizard:
Set the Name to HelloWorldRS and the Resource Path to /hello:
Double-click the process Operational Binding to open the REST Operational Binding editor. Change the URI Parameter from input to name:
Switch to the Response tab. Select JSON as a Payload type.
You can optionally click the Generate Sample Payload button to see what your response will look like in both XML and JSON format:
Click OK, OK and OK to complete the wizard. Save all.
Step 4 – Deploy to API Manager Cloud Service
Right-click the HelloWorld project and select Export and then select Service Bus Resources:
Select Configuration Jar as the Type:
Click Next and select a Export Destination for the Jar File:
Log into your Oracle Cloud account and navigate to your API Manager Service instance. Then click the hamburger icon in the upper right and select the option to Open API Manager Console. Note, this will actually open the Service Bus Console, which is what we want:
In the Service Bus Console, click Create to start a new session. The click the Import Config Jar icon:
Select the Config Jar we just exported:
Accept all the defaults and click Import.
Activate the session:
Step 5 – Test the Services
Open the HelloWorldBS and click the green arrow to Launch Test Console. Optionally change the input string and click Execute. You should see results similar to those below:
If all goes well, open the HelloWorldRS and click the green arrow to Launch Test Console. Set the Accept as either application/xml or application/json and provide a name:
Step 6 – Determine API URL
Testing the API w/in Service Bus is easy. Determining the URL to test the API outside of Service Bus takes some investigative work. In my example, I’m running a single managed server node without a load balancer running at IP address 18.104.22.168:
Therefore, the beginning of my API URL is http://22.214.171.124 (the same address I’ve been using the access the Service Bus Console). If I had a load balancer in place, I would use that IP address instead.
If I log into the the Oracle WebLogic Server Console I see that Service Bus is running on APIManag_server_1 at port 8001. The Oracle Cloud VM automatically routs port 80 to port 8001, so I don’t need to specify the port in my URL.
Return to the Service Bus Console and select the Transport tab of the HelloWorldRS service:
I need to append the Endpoint URI to my base URL. So now I have http://126.96.36.199/HelloWorld/HelloWorldRS.
Finally, I need to specify the resource and optional parameter. If you recall our work in JDeveloper in Step 3, we defined the resource as /hello and the parameter as name. Therefore, our complete API URL is:
If you try to run the API above you will be presented with an Error 403–Forbidden. This is because the API is under the control of the Oracle API Manager and requires an application key (covered next).
Step 7 – Curate the API
Next we will provide metadata on the API which will be published to the API Manager Portal. For more information on this topic, please see Curating APIs Using Oracle Service Bus.
Click the Edit button for the Overview section and provide some details about your API. Don’t forget to include a Test URL so folks know how to use it.
Click Save and then Edit the Publish Status. Set the Status to Published and select Managed. Setting the API to Managed will require a key to be provided to access the service. Click Save.
At this point, our role as an API Developer is complete.
We will now assume the role of an API Admin.
Persona 2 – API Admin
Before APIs can be consumed, users with the application role API Consumer need to first be created so they can log into the API Manager Console.
Step 1 – Create API Consumer Account(s)
For this step we will use the Enterprise Manager Console. We will first create new Group, API Consumers. We will then assign the API Consumer application role to that group. We will then create new users, assigning them to the API Consumers group, therefore inheriting the API Consumer role. Make sense?
Just as we launched the API Manager Console (Oracle Service Bus) in Step 4 above, click the hamburger icon from the API Manager service instance page and launch Oracle Fusion Middleware Control.
Create the API Consumers Group
From the WebLogic Domain dropdown menu, select Security > Users and Groups:
Select the Groups tab and Create a new group, API Consumers:
Assign the APIConsumers role to the API Consumers Group
We need to authorize this new group to access the API Manager Console. From the WebLogic Domain dropdown menu, select Security > Application Roles. Set the Application Stripe to API_Manager and click the blue arrow to Search application roles.
Select the APIConsumer role and click the Edit button. Then add the API Consumers group as a member of the APIConsumer role:
Create Users that can access the API Manager Console
Return to the Security > Users and Groups page. Select the Users tab and Create a new user, APIConsumer. Set a Password for that user.
Edit the APIConsumer user just created, select the Groups tab, and add the user to the API Consumers group:
Create additional user accounts and assign to the API Consumers group as needed.
Note, You can also use an LDAP Authentication provider to manage users. See “Configuring LDAP Authentication Providers” in Administering Security for Oracle WebLogic Server for more information.
Step 2- Enable Analytics
While we are in Enterprise Manager, let’s ensure our operations are being monitored. From the Target Navigation pane on the left, select SOA > service-bus. Then select the Operations tab and click Search. Enable Monitoring for all services and click Apply:
If you skip this step, you will not see any performance metrics in the API Manager Console.
Persona 3 – API Consumer
Now that an API has been made available, let’s put it to use…
Step 1 – Subscribe to the API
Log into the API Manager Portal using the newly created user account, in my case APIConsumer. The application URL is https://<instance IP address:7001/apimanager. In my case, https://188.8.131.52:7002/apimanager. You may want to do this in a private browsing window so that it doesn’t automatically log you in as the weblogic user. The weblogic (admin) user doesn’t have the necessary privileges to create applications and consume APIs.
After logging in you will be greeted by the welcome screen:
From here we can create and manage our applications or browse the API catalog. Since our goal is to consume an API for our application, let’s start there. Click the Red Create and Manage circle to navigate to the Subscriptions page:
We have no API subscriptions or applications. Click the New Application button then provide a Name and Description:
Click Create. Notice the Key that has been provided. This is the key that will need to be provided in order to access the API.
The next step is to add APIs to the application. Clicking Add API takes you to the API catalog. Here you can begin to see some of the metadata we provided in the Service Bus console:
Click the blue information icon to see even more details:
Return to the Hello World REST Service and click the check box icon (next to the information icon) to select the API. Then click the Subscribe button. Now our Greetings application is subscribed to the API.
Step 2 – Consume the API
To test consumption of the API, use your favorite REST client. This could be SOAP UI, RESTClient, Advanced Rest Client, or any number of viable alternatives. At a minimum you need to include the X-API-KEY header:
Since I also want JSON instead of XML returned, I also set the Accept: application/json header:
Persona 2 (again) – API Admin
In order to see usage statistics, the API Manager user must be assigned the APIApplicationAdministrator application role, which my APIConsumer user does not possess. However, my weblogic user does have this role. I can see subscriptions by User or API. Below is the User view. Note I can also see applications w/out any subscriptions as well as unused APIs:
I can also view the performance analytics:
Happy API Managing!