X

The latest cloud infrastructure announcements, technical solutions, and enterprise cloud insights.

Announcing custom domains and certificates and improved logging in API Gateway

Robert Wunderlich
Product Strategy Director

Oracle Cloud Infrastructure (OCI) enables API management through its API Gateway feature. We’re pleased to announce two new features in API Gateway:

This post described these features at a high level and gives you some steps to get started with them.

Custom domains and TLS certificates

This feature lets API development teams choose which certificate the gateway uses to secure traffic. As a result, teams can make their APIs accessible through their own hostname and domain rather than through the hostname that was generated when the gateway was created.

Use cases

Whether you use a default or custom domain and certificate depends on your use case.

Getting started quickly for the developer

When beginning to develop APIs, developers appreciate being able to create a gateway and get started with little effort. With a “default” gateway, the hostname is automatically generated and a common identity certificate is used to secure traffic by default. The default options create a gateway that supports HTTPS traffic and a Domain Name System (DNS) name that uses the following pattern:

<autogenerated_hostname>.apigateway.<oci_region>.oci.customer-oci.com

By using the default DNS option, a developer doesn’t have to create any certificates or configure DNS to get started. While this use case is simple, there are use cases in which choosing a custom certificate and configuring DNS is a necessity.

APIs that represent your brand

An API is an interface and often represents the brand of an organization. As a result, having APIs available under a chosen hostname and domain becomes important.

For example, let’s say that your company is called APIFactory and you want to host your APIs at https://api.apifactory.dev. You need to be able to point clients to your gateway and have a proper certificate that is valid for your host and domain.

Creating a gateway with default DNS

Creating a gateway with default DNS is as straightforward as giving it a name, selecting whether it’s public or private, and choosing your network.

  1. In the Oracle Cloud Infrastructure Console, open the navigation menu, select Developer Services, and then click API Gateway.

  2. Click Gateways, and then click Create Gateway.

    A screenshot that shows the Gateways page in the Console.

    Figure 1: Gateways page

  3. Enter a name for the gateway, choose public or private as the type, and choose the network. Do not select Custom DNS.

    A screenshot that shows the Create Gateway dialog box.

    Figure 2: Create a gateway with default DNS

  4. Click Create.

    In a short time, your gateway is ready, and you can begin to create your API deployments.

    A screenshot that shows the details page for an API gateway.

    Figure 3: Gateway details page

Securing APIs with custom certificates

Now, let’s create a gateway that represents your brand. Before you can start, you need to have a certificate. The certificate secures the traffic between your API clients and your APIs. You could choose to create and use a private certificate, but all of your clients would have to accept that certificate because it wouldn’t be publicly signed. Several certificate authorities, such as DigiCert and Let’s Encrypt, provide public certificates.

Add a certificate to API Gateway

After you create a certificate, add it to the gateway in the Console.

  1. In the API Gateways area of the Console, click Certificates.

    A screenshot that shows the Certificates page in the Console.

    Figure 4: Certificates page

  2. Click Add Certificate.

  3. In the dialog box, enter a name for the certificate and load the PEM files for your public and private keys. Then, click Create.

    A screenshot that shows the Add certificate dialog box.

    Figure 5: Add a certificate

Create a gateway or edit an existing one

You can create a gateway that will use the custom certificate or edit an existing gateway to use it. Either path starts with going back to the main Gateways page in the Console.

A screenshot that shows the Gateways page in the Console.

Figure 6: Gateways page

If you want to create a gateway, follow the previous steps, but select the Custom DNS check box and then choose your certificate.

A screenshot that shows the Create Gateway dialog box with the Customer DNS checkbox selected and a certificate selected.

Figure 7: Create a gateway with a custom certificate

Note: You can use your own certificates for public and private gateways; the experience is the same.

If you want to add a certificate to an existing gateway, go to that gateway’s details page, click Edit, and then select the certificate.

A screenshot that shows the Edit Gateway dialog box with a certificate selected.

Figure 8: Edit a gateway to add a certificate

The Certificates feature makes it easy to add and change the certificates that your gateways use. It also shows you certificates that are about to expire, so you can keep them up-to-date.

Configure DNS

The remaining task is to set up DNS so that clients are properly routed to your gateway. When defining your DNS routing, you can either work with your registrar or use DNS zones within OCI. If your registrar provides the DNS but you want to also use DNS zone, be sure to update your registration to use the OCI DNS name servers.

Following is an example of a zone for apifactory.dev.

A screenshot that shows the DNS Zone page in the Networking section of the Console. A zone named apifactory.dev is listed.

Figure 9: DNS zone

To set up routing, create a record in the DNS zone for the IP address of your gateway. After the updates are propagated, all clients who invoke APIs by using your hostname.domain are routed to your gateway, and the traffic is secured with your certificate.

A screenshot that shows the details page for a zone, with a record listed for the apifactory domain.

Figure 10: Record created in a DNS zone

One of the benefits of DNS zones with Oracle Cloud Infrastructure is that you can use the common Terraform capabilities (or CLI and SDK) provided by OCI to define your architecture of API gateways, certificates, and DNS routing within your common deployment to manage the lifecycle.

API Gateway integration with the Logging service

API Gateway enables you to deliver RESTful APIs that are secure, governed, and managed. A gateway is a network-attached appliance that developers can use to make RESTful services available beyond their organization, such as to partners. By using API Gateway, developers can apply policies that control access, such as JSON Web Token (JWT) validation, as well as rate-limiting and request and response transformations. API Gateway acts as a policy enforcement point and also provides runtime monitoring and logging with the Oracle Cloud Infrastructure Logging service.

Benefits of using Logging with API Gateway

All sorts of systems emit logs, but every log can have a different format and be stored in different locations. The Logging service is based on Fluentd and unifies all types of log sources in a single interface. Services like API Gateway are integrated directly with the Logging service to provide users with a clear and consistent logging experience across all of their services.

One of the key benefits is a structured JSON format for logging, which provides uniformity. As shown in the following example access log, each entry is clearly structured so that the logs can be consumed more easily by downstream systems such as Splunk or Oracle Management Cloud using the OCI Service Connector Hub.

A screenshot that shows part of an access log using JSON format.

Figure 11: Example access log

Logging APIs with API Gateway

API Gateway provides two types of logs: access and execution.

  • Access logs capture the client request invoking an API. This is similar to the HTTP access log that is available in an HTTP server.

  • Execution logs capture information about the steps taken in the API, including requests that were rejected because of policy rules, and invocations to backend systems.

To get started, follow these steps:

  1. On the details page of the API gateway, click Deployments.

  2. Click the name of the deployment that you want to log, and on the deployment details page, click Logs.

    A screenshot that shows the details page for an API deployment with logs disabled.

    Figure 12: Logs for an API deployment

  3. Click the Enable Log for the log that you want to activate.

  4. In the Enable Log dialog box, select the compartment that you’re using for your logs, select the log group, and enter a name for the log. You can also set a retention time.

    A screenshot that shows the Enable Log dialog box.

    Figure 13: Enable a log for an API deployment

  5. Click Enable Log. The log is created and the API traffic logging begins.

    A screenshot that shows the details page for an API deployment with logs enabled.

    Figure 14: Logs enabled for an API deployment

To view the log data, click the log group and use the Logging Search feature. You can search and filter your logs, and quickly identify critical events across multiple logs by using the Explore tab.

A screenshot that shows the Explore tab on the Logging Search page. The tab shows log data entries.

Figure 15: Explore tab on the Logging Search page

Common API pattern that includes API and network-level logging

API Gateway and other OCI services emit logs to the Logging service to provide you with a complete end-to-end view of runtime performance.

A diagram that shows API Gateway and other services in a VCN emitting logs to the Logging service.

Figure 16: Several OCI services emit logs to the Logging service

Conclusion

Learn more about the API Gateway service by reviewing the documentation. And if you haven’t tried Oracle Cloud Infrastructure yet, try it for free today.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha