Web APIs: A Pillar of Digital Transformation

Oracle API Cloud Services - Part 2


By Rolando Carrasco ace-icon-black-18

December 2017

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:

carrasco-web-apis-2-fig001
Figure 1

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

carrasco-web-apis-2-fig002
Figure 2

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

carrasco-web-apis-2-fig003
Figure 3

And we are ready to go!

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

carrasco-web-apis-2-fig004
Figure 4

After clicking Publication, you'll see this:

carrasco-web-apis-2-fig005
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):

carrasco-web-apis-2-fig006
Figure 6

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

carrasco-web-apis-2-fig007
Figure 7

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

carrasco-web-apis-2-fig008
Figure 8

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

carrasco-web-apis-2-fig009
Figure 9

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

carrasco-web-apis-2-fig010
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).

carrasco-web-apis-2-fig011
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).

carrasco-web-apis-2-fig012
Figure 12

The following options for the overview will appear (Figure 13):

carrasco-web-apis-2-fig013
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>


carrasco-web-apis-2-fig014
Figure 14

Click the OK button and you will see:

carrasco-web-apis-2-fig015
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:

carrasco-web-apis-2-fig016
Figure 16

Click on the Apiary button. You will see this:

carrasco-web-apis-2-fig017
Figure 17

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

carrasco-web-apis-2-fig018
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:

carrasco-web-apis-2-fig019
Figure 19

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

carrasco-web-apis-2-fig020
Figure 20

The following screen will appear:

carrasco-web-apis-2-fig021
Figure 21

And finally:

carrasco-web-apis-2-fig022
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:

carrasco-web-apis-2-fig023
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

carrasco-web-apis-2-fig024
Figure 24

Login as Developer and you will see this:

carrasco-web-apis-2-fig025
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).

carrasco-web-apis-2-fig027
Figure 26

Click New Application, then fill in the information (Figure 27):

carrasco-web-apis-2-fig028
Figure 27

Click Save.


Now let's look up the Tickets API. Click the APIs button at the top right of the screen:

carrasco-web-apis-2-fig029
Figure 28

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

carrasco-web-apis-2-fig030
Figure 29

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

carrasco-web-apis-2-fig031
Figure 30

Note that the description we entered earlier now appears.

Click the Documentation button, as indicated in Figure 31:

carrasco-web-apis-2-fig032
Figure 31

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

carrasco-web-apis-2-fig033
Figure 32

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

You will see the following:

carrasco-web-apis-2-fig035
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:

carrasco-web-apis-2-fig036
Figure 34

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

carrasco-web-apis-2-fig037
Figure 35

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

carrasco-web-apis-2-fig038
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):

carrasco-web-apis-2-fig039
Figure 37

You can also see statistics of your application:

carrasco-web-apis-2-fig040
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).

carrasco-web-apis-2-fig041
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).

carrasco-web-apis-2-fig042
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.