Web APIs: A Pillar of Digital Transformation

Oracle API Cloud Services - Part I

By Rolando Carrasco

Web APIs have turned into a key enabler -- indeed, a key pillar -- for digital transformation. Final consumers make use of Web APIs all the time, without even realizing it. Most mobile apps use APIs, without which they would not exist.

Developers also make use of them. They are a key input for the creation of new apps, a key element for the innovation that developers are constantly pursuing.

API providers generate a new economy when they publish APIs and offer them to 3rd parties. When those providers can monetize them, a new income for their organizations is created, creating a new business and increasing the investment in publishing new APIs.

In fact, the perception is that an organization that can offer APIs for 3rd parties is de facto an innovative organization.

But how do we publish APIs? How can we do it in an orderly way? What do we need to get started?

These questions might seem easy at first glance, but it is not so. If you can pass a set of challenges, you will be in a position to identify which APIs make sense to be published -- in other words, which of them can be monetized.

Throughout the process to meet those challenges, there will always be a technology element present so that you can:

Deploy a Web Portal

  • that lets developers look up your APIs
  • that lets developers register their applications and link them to your APIs
  • that lets you publish the APIs you would like the developer to use
  • that lets you share appropriate information for your APIs to be well understood and discovered

Design your APIs and follow the principle of Contract First

Apply policies when you publish your APIs:

  • Security
  • Availability
  • Authorization
  • Etc.

Publish your APIs both on premise and in the Cloud

Have visibility into who is using your APIs and how they're discovering them (usage statistics, etc.)

This article introduces Oracle API Platform Cloud Services, and shows you how it accounts for each of these points.

Publish a New API

Consider a simple scenario. Let's imagine a company that manufactures toys. Those toys are offered to important retailers, both brick and mortar and online. Consumers go to those retailers to buy toys. If a toy has a defect, the consumer will go to the retailer and apply its warranty. The retailers need a communication channel to validate the warranty directly with the manufacturer.

The manufacturer has decided to publish an internal microservice to receive the warranty validation requests. This microservice is already in place for internal purposes, and the idea is to publish it as a Web API for 3rd parties (e.g., the retailers) to use.

The internal team has already build an API blueprint that looks as follows:

http://docs.servicetickets.apiary.io/#

This API was designed with the Contract-First principle, using Oracle Apiary. This is a very powerful and useful tool to design and document APIs; it also has the ability to create mock-ups, test the APIs, etc. It is well targeted to create agility in the documentation, testing and design of APIs.

If we enter the previous URL, we will see the following:

Figure 1

If you want to download the blueprint, simply click the button at the upper left of the screen:

Figure 2

The downloaded file is a text file, of which the following is a piece:

Copied to Clipboard
Error: Could not Copy

FORMAT: 1A
 HOST: http://serviceTicket.demo.oracle.com/
 # ServiceTickets
 Service Ticket is an API to manage Service Tickets. 
  This API fronts both a microservice and a status update 
 REST service from Integration Cloud Service (ICS)
 ## Tickets Collection [/tickets]
 ### List All Tickets [GET]
 Issue a GET request to get a complete list of tickets.
 You can include any of the fields as a filter
 + Request
     + Headers
             Tenant-id: 31
 + Response 200 (application/json)v         {
               "_items": [v                 {
                   "customer": "ACME Corp",
                   "status": "RESOLVED",
                   "product": "Widget",
                  "_id": "589a3774ebee507f7268bcff",
                  "_updated": "Tue, 07 Feb 2017 22:05:38 GMT",
                  "summary": "Customer reports the widget stopped working",
                   "_links": {
                     "self": {
                       "href": "tickets/589a3774ebee507f7268bcff",
                       "title": "Ticket"
                     }
                   },
                   "_created": "Thu, 01 Jan 1970 00:00:00 GMT",
                   "ticketID": "45001",
                   "_etag": "bd584d9a460eabdc979e428e1e0220923b0c5793",
                   "subject": "Widget stopped working"
                 },
                 {
                   "customer": "ACME Corp",
                   "status": "Unresolved",
                   "product": "Widget",
                   "ticketID": "45002",
                   "_updated": "Tue, 07 Feb 2017 21:44:21 GMT",
                   "summary": "Customer reports the widget stopped working",
                   "_links": {
                     "self": {
                       "href": "tickets/589a3fb534605c000176ef5f",
                       "title": "Ticket"
                     }
                   },
                   "_created": "Tue, 07 Feb 2017 21:44:21 GMT",
                   "_id": "589a3fb534605c000176ef5f",
                   "_etag": "cfe52a36fa7a1c738acc994f6e49a8f3f86ce4bf",
                  "subject": "Widget stopped working"
                 },
                 {
                   "customer": "ACME Corp",
                   "status": "Unresolved",
                   "product": "Widget",
                   "ticketID": "45002",
                  "_updated": "Tue, 07 Feb 2017 21:44:37 GMT",
                   "summary": "Customer reports the widget stopped working",
                  "_links": {
                    "self": {
                      "href": "tickets/589a3fc534605c000176ef60",
                      "title": "Ticket"
                    }
                  },
                   "_created": "Tue, 07 Feb 2017 21:44:37 GMT",
                   "_id": "589a3fc534605c000176ef60",
                   "_etag": "dbcf344b1bcaf9fc6781846ed944d147a875394c",
                   "subject": "Widget stopped working"
                 },
                {
                  "status": "RESOLVED",
                   "_updated": "Tue, 07 Feb 2017 21:57:59 GMT",
                   "_links": {
                     "self": {
                      "href": "tickets/589a4133fbcb600001ac564b",
                       "title": "Ticket"
                    }
                  },
                  "_created": "Tue, 07 Feb 2017 21:50:43 GMT",
                  "_id": "589a4133fbcb600001ac564b",
                  "_etag": "a8706300f0a38c1d6aa871901475d2f7a9e29e1d"
                },
                {
                 "customer": "Smithers Corp",
                 "status": "Unresolved",
                 "product": "Idea tablet",
                 "ticketID": "45003",
                 "_updated": "Sun, 12 Feb 2017 21:28:52 GMT",
                 "summary": "When powering up unit, the display is blank",
                 "_links": {
                  "self": {
                     "href": "tickets/58a0d394e0577b0001bcc981",
                     "title": "Ticket"
                     }
                  },
                  "_created": "Sun, 12 Feb 2017 21:28:52 GMT",
                  "_id": "58a0d394e0577b0001bcc981",
                  "_etag": "7a898301b641f1f28dbcf69a6c0dfadf292d6861",
                  "subject": "Display blank"
                }
              ],
               "_links": {
                "self": {
                  "href": "tickets",
                 "title": "tickets"
               },
               "parent": {
                 "href": "/",
                 "title": "home"
               }
             },
              "_meta": {
                "max_results": 25,
                "total": 5,
               "page": 1
              }
             }

Take your time and examine the API blueprint so you can get familiar with it; understand the structure, syntax, semantics, etc. If you are interested in learning this notation, look at this:

https://apiblueprint.org/ 

Let's take a quick look at how we can use Apiary to design and document our API. For that purpose, create an account at https://apiary.io/ and follow these steps:

So far, we have designed, tested and validated an API. Let's go to the Oracle API CLoud Service platform to register and publish it.

Publishing Your First API With Oracle API Platform Cloud Service

Login to the API CS as an API Manager:

Figure 11

You will then see:

Figure 12

Create an API by clicking on the button in the upper right corner of the screen:

Figure 13

Let's review two concepts related to the Endpoints:

Configure those endpoints. To do that, edit your API:

Figure 14

You will see two channels in your API implementation:

Configure the API Request policy:

Figure 15

In this first screen, give the policy a name and input comments to it. Then click on the Next button:

Figure 16

In the Protocol parameter you can choose HTTP, HTTPS or HTTP and HTTPS. The MyGatewayIP is the IP where the gateway is deployed (on premise or in the cloud). Finally, the API Endpoint URL is the name of the resource you want to publish.

Now let's configure the Service Request:

Keep in mind that this is the endpoint of the backend resource that you want to send the request through your API. This can be a Web service or microservice. It can be a service exposed by Oracle SOA Suite or any other SOA platform. It can be any resource with an http/https interface that you want to publish and manage as an API.

In this case, use: http://eserv3.oracle.com:5000/tickets

Figure 17

This first screen concerns the name of the Policy and some comments. The last element locates where we want to apply this Policy. In this case, this policy will be applied right after the API Request.

Click on Next to access the screen where you need to write your backend endpoint. As already mentioned, this is the microservice endpoint:

Figure 18

Our Request channel will look like this:

Figure 19

For demo purposes this example uses the same resource (/tickets) for your API Request as for the Service Request. However, this is not required; the fact that they could be different is one of the benefits of the platform.

If you click in the Response channel, you will see:

Figure 20

Here, the first policy that will be executed is the one related to the response of the backend service, and then your own response (the API). In the middle, you can have more policies that can enrich the response, you can remove elements, or you can include other policies (which will be reviewed in a follow-up article).

API Deployment

So far, we have reviewed how to design an API with Apiary and how to register it within the API Platform using the administration console. Now, let's deploy it to one of our gateways so it can be used by 3rd parties.

Move to the Gateways tab:

Figure 21

From here you can decide to which Gateway you want to publish your APIs. It can be a Gateway that is deployed on premise or in the Cloud.

Your Gateway looks like this:

Figure 22

  • Click on the upper left button to create a New API Project:

    Figure 3

  • You will then see this:

    Figure 4

  • Click Create API and you will get this:

    Figure 5

    On the left side of the screen you can edit the blueprint and on the right side you will start getting a human readable documentation/representation of it. In this way, while you design the blueprint, you will get an automatic documentation for the possible consumers of the API.

  • Copy the blueprint we downloaded in previous steps and paste it in the left side of the screen.
  • After doing this, we have a very complete design of our API. If we modify the left side (e.g., the descriptions), we will see how the right side is immediately updated.

    Figure 6

  • Click the Save button. We have finalized the design of our API. In this case we already had the blueprint, but you get the idea of how you can do it from scratch. In this case, our API has many capabilities:
     
    1. Get all open Tickets: List All Tickets (GET). Resource: /tickets
    2. Create a new Ticket: Resource: /ticket
    3. Update a Ticket (PATCH). Resource: /tickets/{id}
  • Now let's test it. Apiary allows us to both design and test the API. Apiary will create a mock-up for us.
  • Simply click on the resource you would like to test:

    Figure 7

  • You will land on this screen:

    Figure 8

  • Down the screen you will see the Try button. Click it and you will get the response:

    Figure 9

  • Alternatively, you can copy and paste this URL: https://private-ddae1b-serviceticketsotn.apiary-mock.com/tickets  into a browser.

    Figure 10

    1. API Request: This is the endpoint that will be published to end consumers and the outside world.
    2. Service Request: This is the backend Service that will be called after passing all the policies that we will apply to the API. In our example, this endpoint is the microservice that we mentioned at the beginning of this article (the one that is related to the toys warranty).
    1. Request: This is all we want to happen during the request to the API -- we will call to policies. By default there are two policies: API Request and Service Request. They represent the two endpoints that we mentioned previously. If you just configure these two default policies, you will get a passthrough from the API call to your Service endpoint.
    2. Response: This is all we want to happen during the response of the API. We can also apply policies during this process.
  • Note the options listed on the left. Click the fourth icon (the little gear) in the list. This will display the following:

    Figure 23

    From here you can deploy the API to the Gateway bey clicking the Deploy API button, upper right.

    The Deploy API screen will open:

    Figure 24

    Select the Tickets API checkbox. The Deploy button will appear at the button of the screen. The initial state will be Active:

    Figure 25

    Within seconds the new deployment will appear on the Deployed tab:

    Figure 26

    Just like that, you've deployed your first API!

    Once the API is deployed, you can test it using Postman (for example). Since you did not apply any additional policy to your API, you can call the API and get an actual response:

    Figure 27

    Apply Policies to Your API

    It will be difficult to publish APIs without applying some type of policy. The previous steps were just to get familiar with the platform and concepts of Oracle API CS. Now it's time to apply your first policy.

    Let's use the policy Header Validation as a sample to apply a policy. We will simply validate the presence of a header. If the header is not present, we will reject the call.

    Let's get back to your API:

    Figure 28

    On the right side of the screen you will see the list of available policies you can apply (we will discuss this in a second article). For this demo, use the Interface Management - Header Validation:

    Figure 29

    If you place the mouse pointer on top of the Header Validation policy, you will see an Apply button. Click on it to see the following screen:

    Figure 30

    This screen prompts for the name of the policy, comments, and the location of where the policy is to be executed. In this case, it will be executed after the API Request.

    Click Next. You will see:

    Figure 31

    HChoose PASS and ANY. That means that the request will pass if any of the following headers is present (in this case, tenant-id). This value must be greater or equal to 1.

    Now your channel looks like this:

    Figure 32

    Now just redeploy the API to include the new policy.

    Once it's redeployed, if you make the same request to test it, it will return a Bad Request:

    Figure 33

    Now include the header. Use use tenant-id=3:

    Figure 34

    But if you use a value less than 1:

    Figure 35

    You'll get a bad request.

    We've finalized your first contact with Oracle API CS. In our next article, we will talk about policies and will apply more policies to our APIs.

    We will also introduce you to the API Portal, which is the portal to be used by developers.

    >>Continue to Part 2

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