Oracle Cloud Infrastructure (OCI) enables API management through its API Gateway feature. We’re pleased to announce two new features in API Gateway:
Support for custom domains and TLS certificates
Integration with Oracle Cloud Infrastructure Logging
This post described these features at a high level and gives you some steps to get started with them.
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.
Whether you use a default or custom domain and certificate depends on your use case.
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:
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.
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 is as straightforward as giving it a name, selecting whether it’s public or private, and choosing your network.
In the Oracle Cloud Infrastructure Console, open the navigation menu, select Developer Services, and then click API Gateway.
Click Gateways, and then click Create Gateway.
Figure 1: Gateways page
Enter a name for the gateway, choose public or private as the type, and choose the network. Do not select Custom DNS.
Figure 2: Create a gateway with default DNS
In a short time, your gateway is ready, and you can begin to create your API deployments.
Figure 3: Gateway details page
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.
After you create a certificate, add it to the gateway in the Console.
In the API Gateways area of the Console, click Certificates.
Figure 4: Certificates page
Click Add Certificate.
In the dialog box, enter a name for the certificate and load the PEM files for your public and private keys. Then, click Create.
Figure 5: Add a certificate
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.
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.
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.
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.
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.
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.
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 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.
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.
Figure 11: Example access log
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:
On the details page of the API gateway, click Deployments.
Click the name of the deployment that you want to log, and on the deployment details page, click Logs.
Figure 12: Logs for an API deployment
Click the Enable Log for the log that you want to activate.
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.
Figure 13: Enable a log for an API deployment
Click Enable Log. The log is created and the API traffic logging begins.
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.
Figure 15: Explore tab on the Logging Search page
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.
Figure 16: Several OCI services emit logs to the Logging service