An application programming interface (API) is an interface to a service at an endpoint that provides controlled access to a business process or data. Businesses today are treating APIs as a primary product and are adopting the “API First” strategy for increased efficiency, revenue, partner contribution and customer engagement. These companies want to expose their core business values as APIs to partners to bring in more revenue but at the same time secure their core data and processes which enables faster service delivery with low cost.
APIs, Microservices and Cloud
Microservices is an architectural style that is increasingly being used for building cloud native applications, where each application is built as a set of services. These services communicate with one another through contractually agreed upon interfaces – APIs. It is an alternative architecture for building applications which provides a better way of decoupling components within an application boundary.
The number and granularity of APIs that a microservice-based application exposes demands for robust API management that involves creating, publishing APIs, monitoring the life cycle and enforcing usage policies in a secure and scalable environment.
Also, with more and more enterprises of all sizes leveraging cloud platforms to build innovative applications, effective API management in the cloud and/or on-premises is pivotal to meet their business and customer needs.
Oracle API Platform Cloud Service
Oracle’s API Platform Cloud Service (API platform CS) provides an integrated platform to build, expose and monitor APIs to backend services including capabilities like security enforcement, message routing, track usage…etc. This blog will introduce you to the various capabilities offered by Oracle API Platform Cloud Service with the help of a simple use case. The following diagram illustrates the architecture overview of Oracle’s API Platform CS.
API Platform Cloud Service offers a centralized API design with distributed API runtime which makes it easy to manage, secure, and publicize services for application developers by offering innovative solutions.
There are several components in the Oracle API Platform Cloud Service - Cloud Service Console, the Gateway, the Management Portal, and the Developer Portal. Following is a short description of each of these components:
- API Platform Cloud Service Console: Provision new service instances, start and stop service instances, initiate backups, and perform other life cycle management tasks.
- Gateway: This is the security and access control runtime layer for APIs. Each API is deployed to a gateway node from the Management Portal or via the REST API.
- Management Portal: This is used to create and manage APIs, deploy APIs to gateways, and manage gateways, and create and manage applications. You can also manage and Deploy APIs and manage gateways with the REST API.
- Developer Portal: Application developers subscribe to APIs and get the necessary information to invoke them from this portal.
Personas of API life cycle
- API Designer/API Product Manager - Collects customer requirements, documents the API and gets agreement with the consumer on the design of the API
- API Manager/Implementer - Creates, tests, deploys, monitors and manages APIs, apply policies supporting the design and ensuring security
- Gateway Manager - Deploys and configures gateway nodes, reviews and approves API deployment requests, monitors and manages the gateways
- API Consumer - Application developer who consumes APIs to meet the requirements of an application. Searches the API catalog to identify existing APIs, registers desired APIs with application.
Sample Use case
In this blog we will build a simple API called Book Store that exposes functions of an online book store. This blog emphasizes on the API implementation specific features of API Platform CS. To keep things simple we will mock one simple function – list books, which returns a list of books along with their titles, authors and expose it as an API. This blog does not discuss about all the features of Oracle API Platform Cloud Service. Please refer here for comprehensive documentation.
Note: The steps defined in the subsequent sections of this blog assume that you have access to an instance of Oracle API platform Cloud service with Gateway configurations and appropriate user grants to be able to implement and deploy APIs.
Create an API
In this section you create an entry for an API you want to manage in the API Platform CS Management Portal.
1) Sign in to the Management Portal as a user with the API Manager role
2) Click on the “Create API” button to create a new API by providing name, version and description
3) The newly created Book Store API should be listed under the APIs page as shown below:
Register Application to an API
API consumers register their applications to APIs they want to use. Application developers use the Developer Portal to register to APIs while API managers use Developer Portal and the Management Portal. In this section you register an application to the BookStore API.
1) From the APIs page, click the API you want to register an application to and Click on Registrations tab. Click on Register Application to register an application to this API.
2) The following Register Application page comes up listing all the existing applications from which you can choose or you can create a new application.
3) In this case, click on the Create an application link to create a new application and provide the details as in the below screenshot. Click Register button to register the Books App application with Book Store API
4) Once the application is registered with the API, it should be displayed under the “Registrations” tab as follows. Also notice that you can suspend this registration or de-register this application by clicking the respective buttons that appear when you hover on the application name. You can also approve or reject a developer’s request to register their application to an API from this page.
5) Each application that is registered is issued an App key which can be sent along the request to ensure that access to the API is granted only to the registered applications. Click on the Applications tab and click on the Books App application to view the application details along with the App key. You can also re-issue the App key by clicking on the Reissue key button.
Implement the API
Now that we have created an API and registered an application that can access the API, in this section we implement the API by applying policies to configure the request and response flows.
Click on the BookStore API to start implementing the API. The following page comes up with API Implementation activity highlighted.
As a first step of API implementation, we configure the API endpoints. Endpoints are locations at which an API sends or receives requests or responses. APIs in API Platform CS have two endpoints in the request flow:
- API Request
- Service Request
Configure API Request URL
The API Request URL is the endpoint at which the gateway will receive requests from users or applications for your API
1) When you hover on to the API request section, you will see an “Edit” button using which you can configure the API request URL.
2) Click Next to configure the URL as follows. In the API Endpoint URL field, provide the endpoint URL for the Book Store API, apply and save the changes.
In this case we have specified /bookstore/books to be the relative URI. You can also choose the protocol to be HTTP or HTTPS or both.
Create a backend service
We need to create a backend service that would process the requests forwarded by the bookstore/books API. As mentioned earlier, we create a mock implementation of this service using Apiary. Oracle Apiary provides you with the ability to design APIs using either API Blueprint or Swagger 2.0. Please refer to http://apiary.io to learn more about Oracle Apiary, its features and to register for a free account.
Note: This task assumes that you have already registered with Apiary and have valid access credentials to login into Apiary.
1) Navigate to http://apiary.io and Sign In using your account
2) Create a new API by clicking on Create New API project as follows, you can choose to design your API using API Blueprint or with Swagger. In this case we use API Blueprint, click on Create API button to create the Book Store API.
3) The API editor opens with a sample API definition which can be edited to define the API for /books as follows:
For the sake of simplicity, just replace the content in the left window with the following text. We have mocked the implementation of /bookstore/books service by providing two book entries.
Bookstore is a simple API allowing consumers to view all the books along with their title and author.
## Books Collection [/bookstore/books]
### List All Books [GET]
+ Response 200 (application/json)
"Title": "Thus Spoke Zarathustra",
"Author": "Friedrich Nietzsche"
"Title": "The Fountainhead",
"Author": "Ayan Rand"
4) When you click on Save button, you should see the right side window updated accordingly, based on the content you just provided.
5) When you click on the List All Books link, you will see the following page with a mock server URL (https://private-2dd84-bookstoreapi.apiary-mock.com/bookstore/books , note that this URL would be different when you try to execute this example) for the /bookstore/books API service implementation
6) Click on the Try button to invoke the mock service URL and validate the output. You will see a HTTP 200 response with the following output on the right side window. This confirms that the mock service URL is returning the book entries in response.
Configure Service Request URL
The service request is the URL at which your backend service receives requests. The gateway routes the request to this URL when a request meets all policy conditions to invoke your service.
1) Click on the “Edit” button you see when you hover on the Service Request section on the API Implementation page
2) Enter the policy name and provide description and click on Next as shown below
3) In the Backend service URL input field, provide the mock server URL that was noted in step #5 in the above section as follows. Apply and Save the changes.
You can apply policies to an API to secure, throttle, route, or log requests sent to it. Requests can be rejected depending on the policies applied, if they do not meet criteria specified for each policy.
1) The API Implementation page lists all the policies currently supported as follows, you can apply any policy by hovering onto the policy name and clicking on the Apply button.
Configuring all policies is beyond the scope of this blog, we apply couple of security and traffic management polices to the BookStore API to illustrate how to manage APIs by applying the policies. Please refer to Applying Policies section of API Platform CS documentation for more details.
Note: Policies in the request flow can be used to secure, throttle, route, manipulate, or log requests before they reach the backend service while polices in the response flow manipulate and log responses before they reach the requester.
2) Let us say we want to restrict the BookStore API to be consumed only by a specific application, a key validation policy can be applied on the request flow which ensures that requests from unregistered (anonymous) applications are rejected.
- As discussed in Register Application to an API section above applications can be registered to an API and a unique App key is generated and assigned for each application.
- These keys can be distributed to clients when they register to use an API on the Developer Portal.
- At runtime, if this key is not present in the given header or query parameter, or if the application is not registered, the request is rejected.
To apply this policy, hover on the key validation policy under Security and click on Apply button. In the policy configuration page, give a name to the policy and you can specify the order in which this policy has to be triggered by selecting the policy from "Place after the following policy" drop down. Currently we have API Request policy that is already configured.
When you click the Next button you can specify the key delivery approach. The application key can be passed in header or as a query parameter. In this case we choose Header and specify the key name as “api-key”, click on Apply and save the changes. At runtime, the request is parsed for this key name and if found its value is validated against the registered application’s App key value. The request would be processed only if the values match else they would be rejected.
3) Let us apply another policy to restrict the number of requests our BookStore API can take within a specific time period. An API rate limiting policy can be used to limit the total number of requests an API allows over a time period that you specify, this time period can be defined in seconds, minutes, hours, days, weeks, or months.
To configure this policy, hover on the API Rate Limiting policy under Traffic Management and click on Apply button, in the resulting page provide a policy name and specify the order in which this policy should be triggered, in this case we want this policy to be triggered after the key validation policy.
Click Next to configure the time period and the number of requests. We want the Gateway to reject requests for this API if they exceed 5 per minute.
Note: Other traffic management related policies like API throttling can be implemented to delay request processing if they exceed the set threshold. Please refer to the API platform CS documentation for more details.
The API implementation should look like below after configuring the above policies:
Deploy the API
In this section you will deploy the BookStore API to a gateway and activate the API. To deploy an endpoint, API Managers must have the Manage API or Deploy API grant for the API in addition to the Deploy to Gateway or Request Deployment to Gateway grant for a gateway.
Note: This task assumes that the gateway nodes are configured and the user has the required grants to be able to deploy the API to the gateway. Please refer to Managing Gateways section for more details on configuring Gateways and their topology and Grants section for more details on granting users access to resources.
1) To deploy the API to the gateway, click on the Deployments icon just below the API Implementation.
2) Click on the Deploy API button, the resulting page lists all the gateways configured and allow you to choose a gateway onto which you want to deploy this API to. You can also choose the Initial deployment state of this API
Please note that the gateways can be configured anywhere - on oracle cloud , or third party cloud or on-premise.
3) When you click on the Deploy button, a request for API deployment is submitted and once the deployment is successful, the Deployments page would look as follows showing the Gateway Load Balancer URL which is your endpoint for sending the API requests.
Invoke the API
Now that you have successfully implemented your API and deployed the API to the gateway, you can send requests to the API and validate if the policies work as intended.
You can use Postman or any other REST client to send requests to the API. In this case we use Postman to invoke the API.
Scenario # 1
Open Postman and initiate a GET request to the Load Balancer URL that has been shown on the Deployments page.
The request to the API fails with error – 401 (Unauthorized access), this is because the key validation policy got triggered and was looking for a header called “api-key”, which we have not set while submitting the request.
Scenario # 2
Add a request header with key as “api-key” and provide the App key of the registered BooksApp as value and submit the request. This will return a couple of book entries which we have mocked as part of the API service implementation in Apiary.
Scenario # 3
Submit 5 requests to this API within a minute time period; you will see the response from the API retrieving the book entries. When the request for the API is made for the 6th time within 1 minute, the API Rate limit policy that we have configured gets triggered and rejects the request as shown below:
The requests submitted after sometime (when the invocation rate comes to acceptable limit) are accepted and processed as usual again until any policy execution fails.
Once the API has been tested, you can publish this API to development portal from where developers can discover the API and register apps for consuming the APIs. Also API Platform Cloud Service Management Portal provides Analytics around who is using your API, how APIs are being used, and how many requests are rejected along with other metrics like request volumes…etc. Discussion on these aspects is beyond the scope of this blog.
This blog discussed about the concepts of API management and its importance in the context of Microservices and cloud native applications. It provides an overview of Oracle API Platform Cloud Service and briefly discussed about its key components. Using a simple use case we illustrated how APIs can be created, configured, deployed, consumed and monitored using Oracle API platform Cloud service. This blog is limited to discuss specific aspects of Oracle API platform CS, please refer to Oracle API platform CS documentation for further details.
The views expressed in this post are my own and do not necessarily reflect the views of Oracle.