Web APIs: A Pillar of Digital Transformation

Oracle API Cloud Services - Part I


By Rolando Carrasco ace-2

August 2017

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:

  1. Deploy a Web Portal

    1. that lets developers look up your APIs
    2. that lets developers register their applications and link them to your APIs
    3. that lets you publish the APIs you would like the developer to use
    4. that lets you share appropriate information for your APIs to be well understood and discovered
  2. Design your APIs and follow the principle of Contract First
  3. Apply policies when you publish your APIs:

    1. Security
    2. Availability
    3. Authorization
    4. Etc.
  4. Publish your APIs both on premise and in the Cloud
  5. 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:

carrasco-web-apis-fig001
Figure 1

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

carrasco-web-apis-fig002
Figure 2

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

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:

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

    carrasco-web-apis-fig003
    Figure 3

  2. You will then see this:

    carrasco-web-apis-fig004
    Figure 4

  3. Click Create API and you will get this:

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

  4. Copy the blueprint we downloaded in previous steps and paste it in the left side of the screen.
  5. 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.

    carrasco-web-apis-fig006
    Figure 6

  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}
  7. Now let's test it. Apiary allows us to both design and test the API. Apiary will create a mock-up for us.
  8. Simply click on the resource you would like to test:

    carrasco-web-apis-fig007
    Figure 7

  9. You will land on this screen:

    carrasco-web-apis-fig008
    Figure 8

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

    carrasco-web-apis-fig009
    Figure 9

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

    carrasco-web-apis-fig010
    Figure 10

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:

carrasco-web-apis-fig011
Figure 11

You will then see:

carrasco-web-apis-fig012
Figure 12

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

carrasco-web-apis-fig013
Figure 13

Let's review two concepts related to the Endpoints:

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

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

carrasco-web-apis-fig014
Figure 14

You will see two channels in your API implementation:

  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.

Configure the API Request policy:

carrasco-web-apis-fig015
Figure 15

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

carrasco-web-apis-fig016
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

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

carrasco-web-apis-fig018
Figure 18

Our Request channel will look like this:

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

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

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

carrasco-web-apis-fig022
Figure 22

Note the options listed on the left. Click the fourth icon (the little gear) in the list. This will display the following:

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

carrasco-web-apis-fig024
Figure 24

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

carrasco-web-apis-fig025
Figure 25

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

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

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

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

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

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

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

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

carrasco-web-apis-fig033
Figure 33

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

carrasco-web-apis-fig034
Figure 34

But if you use a value less than 1:

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