Web APIs: A Pillar of Digital Transformation Oracle API Cloud Services - Part 2

In Part 1 of this series we learned how to:

• Model and design our first API with Oracle Apiary
• Create the API using the API Manager of Oracle API Platform Cloud Services
• Deploy the API into an API Gateway
• Modify our API to include a simple Header Validation

In this article, we will learn how to:

• Publish APIs to the API Portal
• Enter the API Portal as a developer to register an application and subscribe to an API
• Generate an API key to use the API
• Consume the APIs

Let's do it!

How to Publish APIs to the API Portal

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:

• Identity those developers
• Manage them
• Communicate to them any changes in our APIs
• Understand how they're using the APIs
• Receive feedback from them

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:

(https://<hostname>:<port>/apiplatform)

Login as an API manager user:

Figure 1

Once logged in, look for the Tickets API (the one we created in the previous article):

Figure 2

Click on it and you will be redirected to the API configuration:

Figure 3

And we are ready to go!

The first step is to go to the Publish section of the API:

Figure 4

After clicking Publication, you'll see this:

Figure 5

From here, we can:

• 1. Configure the API Portal URL where the API will be published
• 2. Create a description of the API
• 3. Document the API in different ways:
  • HTML / Markdown. Here we will write anything that can describe the API
  • Connect it with Apiary. As we learned in our previous article, this is very simple and straightforward. And since it is part of our API Platform Cloud Service, let's leverage it and reuse all the documentation that Apiary has already created for our API.

Let's configure the API Portal URL. Click on the URL section highlighted in yellow (Figure 6):

Figure 6

Type in "tickets" and then click the checkmark at the right.

Figure 7

The green Publish to Portal button will appear to the right of the URL:

Figure 8

Publish to Portal will be disabled. To enable it, simply click the Save Changes button at the top right of the screen.

Figure 9

Click on the now-enabled Publish to Portal button to publish the API to the Portal. You will then see:

Figure 10

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).

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).

Figure 12

Figure 13

In the Overview section you can:

• File: Upload a File with the overview of the API
• Text: Write some HTML (Text tab) to describe the API
• Link: Include a Link to an external URL where the API is described

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> 

Figure 14

Click the OK button and you will see:

Figure 15

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:

Figure 16

Click on the Apiary button. You will see this:

Figure 17

Click the Continue to Sign in button and input your credentials:

Figure 18

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:

Figure 19

At the bottom of the screen, click the green Connect button.

Figure 20

The following screen will appear:

Figure 21

And finally:

Figure 22

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:

Figure 23

Now, let's take on the role of a developer who is interested in our API.

Enter the API Portal as a Developer to Register an Application and Subscribe to an API

Let's head to this location:

https://<yourAPIPCSURL>/developers/login

Figure 24

Login as Developer and you will see this:

Figure 25

As a developer you can:

• Search for APIs
• Order APIs in alphabetical order
• Manage Applications and APIs

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).

Figure 26

Figure 27

Figure 28

Use the search text box to find the Tickets API (Figure 29):

Figure 29

Click on Tickets. The API information is displayed (Figure 30).

Figure 30

Note that the description we entered earlier now appears.

Click the Documentation button, as indicated in Figure 31:

Figure 31

The API documentation created in the previous article opens in Oracle Apiary (Figure 32).

Figure 32

Now simply click on the blue Subscribe button in the upper right (as seen in Figure 31).

You will see the following:

Figure 33

Select the application that we created earlier (TysForUsTicketsApp). After checking the box, you will see the following at the right side of the screen:

Figure 34

Click on Subscribe API button. You will return to the documentation screen, but now you will see this:

Figure 35

Click on the TysForUsTicketsApp link (highlighted in yellow in Figure 35).

Figure 36

The API Key that the application needs to use the Tickets API is displayed. You can also manage grants for users (Figure 37):

Figure 37

You can also see statistics of your application:

Figure 38

Now let's consume our API.

Consuming the API

If you try to use the API without providing the API Key, you'lll get an http 401 Unauthorized code (Figure 39).

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).

Figure 40

Now we can see the result of the call.

About the Author

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.