My first steps with Oracle Cloud API Gateway – the stock response

0

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.

image

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:

image

In Chrome this looks nicer:

image

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)

    image

    The only thing I provided was de name for the VCN; I accepted all other defaults.

    imageimage

    image

    image

    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:image

      Click on the Security List for the public subnet:image

      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:image

      Click on Add Ingress Rules to have the new traffic rule set up:image

      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.

      image

      image

      image

      image

      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.

      image

      image

      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:

      image

      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.

      image

      Press Save Changes.

      The new API Deployment will now be activated. Saving or updating a deployment takes 30 seconds to one minute.

      image

        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

        image

        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

        image

        Log files are written to OCI Object Storage. The Bucket is created automatically – I did nothing to enable this.

        image

        Inspecting the bucket:

        image

        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:

        image

        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:

        image

        It forwards to the AMIS Technology Blog:

        image

        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

        About Author

        Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director and Oracle Developer Champion. Solution architect and developer on diverse areas including SQL, JavaScript, Kubernetes & Docker, Machine Learning, Java, SOA and microservices, events in various shapes and forms and many other things. Author of the Oracle Press book Oracle SOA Suite 12c Handbook. Frequent presenter on user groups and community events and conferences such as JavaOne, Oracle Code, CodeOne, NLJUG JFall and Oracle OpenWorld.

        Leave a Reply

        This site uses Akismet to reduce spam. Learn how your comment data is processed.