By Rolando Carrasco
In Part 1 of this series we learned how to:
In this article, we will learn how to:
Let's do it!
Either for internal or external purposes, it's necessary to have an API Portal where 3rd parties or internal developers can register applications to subscribe to APIs. Our API management strategy will be successful only if developers actually use our APIs. And if that happens, we need to:
An API Portal is key to enabling this communication. Oracle API Platform Cloud Service offers an out-of-the-box portal that you can use to fulfill the requirements listed above. In the next section of this article we will publish our Tickets API to the API Portal.
The following steps are performed within the API Manager Portal:
Login as an API manager user:
Once logged in, look for the Tickets API (the one we created in the previous article):
Click on it and you will be redirected to the API configuration:
And we are ready to go!
The first step is to go to the Publish section of the API:
After clicking Publication, you'll see this:
From here, we can:
Let's configure the API Portal URL. Click on the URL section highlighted in yellow (Figure 6):
Type in "tickets" and then click the checkmark at the right.
The green Publish to Portal button will appear to the right of the URL:
Publish to Portal will be disabled. To enable it, simply click the Save Changes button at the top right of the screen.
Click on the now-enabled Publish to Portal button to publish the API to the Portal. You will then see:
The API has been published and a URL to the API Portal has been created with the /tickets resource at the end of it. If you want to unpublish, click the green button on the right.
Now let's write a brief description of our API in the Developer Portal API Overview (Figure 11).
Whatever we write/document here will appear in the Developer Portal as the description for our API. You must write something appealing in order to get the attention of possible users. Simply click on the HTML/Markdown button (Figure 12).
The following options for the overview will appear (Figure 13):
In the Overview section you can:
Let's use the Text tab to write a very simple HTML for our overview. Simply copy and paste the following html into the Text tab (Figure 14).
<p>Currently this Tickets API is designed to return the list of open tickets
that your store has with us. It is designed to return the tickets that
your customers have opened regarding malfunctions of our toys.</p>
<p>In the future this API will offer:</p>
<p>1. Tickets creation</p>
<p>2.Tickets by toys</p>
<p>3.Tickets by customer</p>
<p>4. Tickets about to expire</p>
Click the OK button and you will see:
Now let's make the final configuration to complete the documentation of our API. Remember that all this is for the benefit of developers who will engage with the APIs. This final step is to connect it with Apiary. Let's focus on this section of the page:
Click on the Apiary button. You will see this:
Click the Continue to Sign in button and input your credentials:
Click the green Sign In button. You will then be prompted to choose the Apiary collaborative (team) project you would like to connect with. In this case, let's choose the ServceTickets project:
At the bottom of the screen, click the green Connect button.
The following screen will appear:
We have finalized the configuration to publish the API on the API Portal. Simply click the Save Changes button at the top right of the screen:
Now, let's take on the role of a developer who is interested in our API.
Let's head to this location:
Login as Developer and you will see this:
As a developer you can:
The first thing we are going to do is to create an application that will be subscribed to our Tickets API. In our hypothetical scenario, this is a 3rd-party retail company that wants to create an app that uses the Ticket API. Let's imagine that this 3rd party retailer is going to build a brand new app for their services organization, with the purpose of consolidating tickets management and creation for different brands.
To do that, click the My Applications button at the top right of the window. The My Applications window will open (Figure 26).
Click New Application, then fill in the information (Figure 27):
Now let's look up the Tickets API. Click the APIs button at the top right of the screen:
Use the search text box to find the Tickets API (Figure 29):
Click on Tickets. The API information is displayed (Figure 30).
Note that the description we entered earlier now appears.
Click the Documentation button, as indicated in Figure 31:
The API documentation created in the previous article opens in Oracle Apiary (Figure 32).
Now simply click on the blue Subscribe button in the upper right (as seen in Figure 31).
You will see the following:
Select the application that we created earlier (TysForUsTicketsApp). After checking the box, you will see the following at the right side of the screen:
Click on Subscribe API button. You will return to the documentation screen, but now you will see this:
Click on the TysForUsTicketsApp link (highlighted in yellow in Figure 35).
The API Key that the application needs to use the Tickets API is displayed. You can also manage grants for users (Figure 37):
You can also see statistics of your application:
Now let's consume our API.
If you try to use the API without providing the API Key, you'lll get an http 401 Unauthorized code (Figure 39).
But if we add the x-api-key header and include our API Key, we will be able to consume the API (Figure 40).
Now we can see the result of the call.
Oracle ACE Rolando Carrasco is a SOA Architect and co-founder of the S and P Solutions team in Mexico and Latin America. He's been working with Oracle SOA since 2003/2004, and his professional career has been focused on the integration space. Rolando is also co-director of the Oracle Users Group in Mexico (ORAMEX), and co-founder of the SOA MythBusters blog.
This article has been reviewed by the relevant Oracle product team and found to be in compliance with standards and practices for the use of Oracle products.