The API Gateway service on Oracle Cloud Infrastructure went live very recently – read my overview article of what API Gateway entails. In brief: API Gateway is a reverse proxy that exposes HTTP endpoints on which external (or internal) clients can make requests. API Gateway can handle these requests: authorize, rate limit, map and route to OCI internal or public HTTP endpoints or specifically to Oracle [serverless] Functions. API Gateway allows us to allow selective public access to private OIC endpoints.
In this article I will briefly show how I got going with API Gateway, although in all honesty the Oracle provided resources I used tell very much the same story I will tell. One big warning: when I thought I had it all set up correctly and expected successful calls, nothing happened when I made my requests to the API Gateway endpoint. My requests timed out. As if the API Gateway endpoint did not exist. My mistake of course. After running the Network Quick Start Assistant – a great tool by the way – you have to take one extra step: create a network security rule in the regional subnet with which the API Gateway will be associated to allow inbound traffic on port 443. If you forget this step (as I did) the API Gateway’s endpoint is not accessible.
Now the steps for creating the first and simplest API endpoint on API Gateway are:
- create a Compartment on OCI
- run Networking Quickstart wizard (to create VCN, subnets, internet gateway, NAT gateway, service gateway)
- add network security rule to allow inbound traffic to subnet on port 443
- add policies allowing API Developers to manage API Gateway and associated resources (note: if you create the API Gateway as an administrator – as I did – these policies do not have be explicitly defined)
- create API Gateway [instance]
- define and publish API [deployment]
- call the API
You should be able to complete these steps in 10-15 minutes.
Below I will share the screenshots from my first steps. An excellent and straightforward set of instructions is provided here: Oracle Cloud Infrastructure API Gateway – Set up, creation, and deployment – so you might as well skip my instructions.
The first API [deployment] I created has a backend of type stock response: it returns a static response – which can contain headers (header values up to 4KB), the response code and the response body (maximum of 5 KB); the stock response might even be a very simple way of providing configuration data or fairly static reference data to clients.
After deploying the API definition, I can invoke it at the assigned endpoint, through simple Curl:
curl -k -v GET https://ohv265mm.apigateway.us-ashburn-1.oci.customer-oci.com/health/v1/stock
with /health/1 is the API Gateway’s endpoint and /stock is one of the routes I have defined.
The response contains of course the custom headers and stock response body – as well the opc-request id that could be used for tracking & monitoring/log analysis:
In Chrome this looks nicer:
Screenshots of the steps towards getting my first API running on OCI API Gateway
I will skip the screenshot for creating a Compartment on OCI; there is something special about this compartment.
Run Networking Quickstart wizard
(to create VCN, subnets, internet gateway,
NAT gateway, service gateway)
The only thing I provided was de name for the VCN; I accepted all other defaults.
When the wizard is done, all necessary network configuration has been performed. Well, maybe not really all. See next section.
Add network security rule to allow inbound traffic to subnet on port 443
The step I overlooked – causing me some grieve and initial disappointment. Robert Wunderlich responded to my query with amazing speed – especially given our time zone dislocation – and stopped my tears.
Go to the VCN. Click on the public subnet:
Click on the Security List for the public subnet:
Add a new ingress rule – one that specifies that traffic is allowed on port 443, in this case from all source IP addresses. Note: this is where we can define IP Whitelisting – by restricting the range of source CIDR:
Click on Add Ingress Rules to have the new traffic rule set up:
Add policies allowing API Developers to manage API Gateway and associated resources
(note: if you create the API Gateway as an administrator – as I did – these policies do not have be explicitly defined) So no screenshots from me
Create API Gateway [instance]
At last we are doing API Gateway specific things.
It takes less than one minute to create an API Gateway [instance].
Define and publish API [deployment]
Once the API Gateway is up and running, we can start defining API (deployments) with their specific endpoints and routes (at sub URL paths) to back ends.
Here I define the API Deployment api-gw-health with path prefix /health/v1. This prefix will be used in the endpoint address, right after the API Gateway endpoint. API Request Policies can be specified for the API and to some extent (such as CORS) per Route. The Authentication Request Policy allows me to associate an Oracle Function with this API; this function will be invoked for each API request, to perform the authentication, authorization and validation that is implemented in that function.
Press Next for defining the Routes:
Route 1 has /stock as path – which brings the total URL endpoint for this API Route to: https://<API Gateway Endpoint>/health/v1/stock. Note: an API [deployment] can contain many routes. It seems that routes cannot be renamed – they are simply numbered – Route 1, 2 etc. If there are many routes in an API, I expect this will get a little hard to keep track of. It would be nice to be able to give routes a specific name and be able to easily navigate to the route definition we need – for example by adding the names of the routes as sub-stations in the train route shown on the left.
The type of backend for this route is Stock Response (static response). I have specified a custom body as well as two custom headers and the HTTP status code (200).
Press Next.
Press Save Changes.
The new API Deployment will now be activated. Saving or updating a deployment takes 30 seconds to one minute.
Invoke API – then inspect monitoring and logging
The new API can be invoked like any HTTP(S) endpoint – from a browser, using Curl on the command line, with Postman
Of course this is not spectacular: I defined a declarative, static response for an HTTP request and when I make the call,I get the response. It is almost like programming and deploying and running a simple Servlet. Except of course that all these steps were quite simple. Once the API Gateway is up and running, every additional API and Route is dead simple to add. And this static response is really only the tip of the iceberg. The next steps are bringing Functions to the forefront.
Metrics can be checked per API Gateway and per API Deployment. Here is an idea of the total overview – with number of requests, latency (response times) and number of bytes processed
Log files are written to OCI Object Storage. The Bucket is created automatically – I did nothing to enable this.
Inspecting the bucket:
The gateway level log files provide an overview of the number of calls and the time they took to complete; note that the OPC Request Id is included:
API Gateway as HTTP Request Forwarder
As a somewhat silly example, I have created the following route, to demonstrate that Routes do not have to relay to OCI resourcs:
It forwards to the AMIS Technology Blog:
Resources
Documentation on API Gateway: https://docs.cloud.oracle.com/iaas/Content/APIGateway/Concepts/apigatewayoverview.htm
Tutorial: Oracle Cloud Infrastructure API Gateway – Set up, creation, and deployment
Tutorial/Blog: Creating Your First API Gateway In The Oracle Cloud
Oracle Cloud Native – Oracle Cloud Infrastructure API Gateway: https://www.oracle.com/cloud/cloud-native/api-gateway/
Blog The Cloud Native Approach to Extending your SaaS Applications with a good example of a scenario of using API Gateway and an explanation of how the Authorizer Function fits into the story
