Table of contents
Introduction
Oracle REST Data Services (ORDS) is an incredibly versatile tool for building REST APIs on the Oracle Database (and MySQL). Used in conjunction with Oracle Cloud Infrastructure (OCI) services such as API Gateway, you can take your ORDS APIs to the next level.
This post will discuss Oracle OCI API Gateway and the features that may lead you to consider deploying it in front of your ORDS REST services.
What is OCI API Gateway?
The OCI API Gateway service enables you to publish API endpoints. The endpoints support API validation, request and response transformation, CORS, authentication and authorization, usage plans, and request limiting. API Gateways sit between your API logic and external consumers. API Gateways can perform several activities not central to your core API logic to remove this overhead from your infrastructure and allow you to focus on the business logic in your ORDS APIs.
Here is a simplified view of how API Gateway sits in your architecture.
Note: Depending on your situation, you may need a Load Balancer before API Gateway and/or between API Gateway and your ORDS servers.
API Gateway Service Limits
It is essential to be aware of the API Gateway Service Limits. For example, the maximum timeout value you can set when API Gateway calls your backend service is 60 seconds.
Why not use a Load Balancer?
You may notice that some features I discuss in this post could also be handled by a Load Balancer. Given that you will likely need a Load Balancer anyway, API Gateway may not be necessary if you do not need any API Gateway-specific features. For example, if you only need to simplify/abstract your API URL, and route requests, then a Load Balancer will suffice.
API Gateway Features
Configured correctly, ORDS is a highly performant and resilient solution for publishing REST APIs. API Gateway can, however, introduce several features that can bolster your ORDS API platform. This section describes several API Gateway features that may make you consider adding API Gateway in front of your ORDS REST APIs:
Abstract (& simplify) API EndPoint URLs
As soon as you publish APIs to consumers, it is tough to make changes to your APIs that won't break something in their code. If your consumers point to a URL on API Gateway, you can quickly move the ORDS servers/URLs and point the API Gateway deployments to the new ORDS servers/URLs. Your consumers would not even know there was a change.
Depending on your ORDS setup, your REST API URLs might be long and complicated. e.g., https://example.com/dbmapping/ords/carschema/carmodule/cars. You could set up an API Gateway Endpoint https://api.example.com/cars that points to your ORDS URL, simplifying the URL for your consumers.
Authentication
ORDS allows you to create REST APIs secured using ORDS' own OAuth2 server. If you need to use the same Authentication and Authorization across all REST APIs in your organization, then API Gateway offers the following Authentication Options:
HTTP Basic Authentication
API Key Authentication
OAuth Authentication and Authorization
Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) with Identity Domains Authentication
Oracle Identity Cloud Service (IDCS) Authentication
Note: If you do not use ORDS OAuth2 Client Credential, you need to consider how you will identify the current user/client within your ORDS service logic. ORDS offers the current_user bind variable, which returns the OAuth2 Client ID for the current API invocation. This is useful when applying SQL WHERE clauses to restrict access to data to specific clients. You won't get this bind variable if you use API Gateway Authentication.
Rate Limits
An essential part of protecting your API infrastructure is to ensure that it cannot be abused with thousands of unauthorized connections. API Gateway offers rate-limiting capabilities that block connections if they perform too many requests in a given period. For example, you could set up a rate limit to block requests from an IP if it makes more than ten requests per second. Once blocked, these requests never make it to your ORDS servers allowing them to focus on genuine requests.
If a particular IP address calls your API too many times in the configured period, it will receive a 429 'Too Many Requests' response.
{
"code": 429,
"message": "Too Many Requests"
}
Usage Plans
If you have a public API, you may want to provide plans to your customers based on subscriptions. For example, Customer A may have purchased a plan to allow them to call your API 1,000 times/month, while customer B may have a plan for 20,000 calls/month.
API Gateway Usage Plans allow you to provide specific API consumers with plans to limit the number of times they can access your API in a given period.
When calling your API gateway Endpoint, clients need to pass an additional identifier which is checked against the usage plan. For example, the client could pass their OAuth2 Client ID in the HTTP Header client-id. API Gateway checks the value against the usage plan, and if the client has exceeded the plan limits, they will receive a 429 'Too many requests' HTTP response.
You can also mix in Rate Limits with usage plans. This means you could set up a rule where a client can call your API 10,000 times a month in total but cannot make more than 100 requests per minute.
Request Policies
Many times consumers will send invalid requests to your ORDS APIs. They may miss a required HTTP header or pass XML instead of JSON. Your ORDS APIs can waste time and resources in performing these basic validations.
API Gateway can be configured to apply Request Policies to requests before they are passed on to your ORDS API. Request Policies Allow you to validate:
Required HTTP Headers
Required Parameters
A valid content type for the body of a request. For example,
application/json,application/xml
If a request policy fails, an appropriate HTTP error code is returned to the client. For example, if you applied a valid content type policy of application/json, and a client tried to call your API with a content type of application/x-www-form-urlencoded, they would receive a 415 Unsupported Media Type error with a response similar to the one below.
{
"message": "Unsupported Media Type: Body validation error\n Unsupported Content-Type 'application/x-www-form-urlencoded'. Supported: 'application/json'.",
"code": 415
}
Transformations
Request Policies also allow you to perform transformations between the request sent to API Gateway and the request sent to your ORDS API. You can perform Header and Parameter transformations on inbound requests. This allows you to exclude, rename, and alter the value of HTTP Headers and Parameters before they are passed on to your ORDS service.
This might be useful if you wanted to add a customer HTTP header to the request that goes to ORDS to inform ORDS that the request came from the API gateway.
You can also exclude, rename, and alter HTTP Headers in the response from ORDS back to the consumer. This may be useful if you want to remove some of the HTTP headers ORDS produces before returning the response to the consumer.
Response Caching
What if client requests could be served entirely by API Gateway without ever reaching your ORDS server? This can be achieved using API Gateway Response Caching. This setup is a little more complex and involves setting up and securing a cache server.
API Gateway evaluates a request using cache keys (method and request URL). If a request matches an entry in the cache for the key, it will fetch and return the cache entry instead of calling your ORDS service. API Gateway also handles adding entries to the cache if they do not exist.
The benefits in terms of response times to your consumers and reduced load on your ORDS servers (and database) could be significant. The benefits depend on the type of data you are serving. If your data is highly dynamic, caching may be less effective, but if you expect multiple consumers to make the same request in a short period, then response caching may be worth looking into. I should also point out that caching may not make sense if your volumes are not in the thousands of requests per minute.
Logging
Logging is an important part of an API strategy. You need to know how often your APIs are called and how often they fail. If you own your ORDS install and have access to the ORDS server, you can configure logging through ORDS and examine the log files as necessary. However, if you are using the Autonomous or APEX OCI Service, you may not have access to the log files (unless you install customer-managed ORDS).
You can configure logging in API Gateway to log requests made through API Gateway. API Gateway uses the Oracle Cloud Infrastructure Logging service. You can enable two types of logging access logging and execution logs.
Access Logs
Access logs record a summary of every request and response that goes through the API gateway to and from an API deployment. Here is an example of an entry in an API Gateway access log:
{
"datetime": 1676040182298,
"logContent": {
"data": {
"bodyBytesSent": 45,
"gatewayId": "ocid1.apigateway.oc1.iad.amaaaaaamm46asyaymb3cbyejy5oood7au3luggakiuwtsju2m6ma7ac23la",
"httpUserAgent": "ABCCORP",
"message": "GET /devcndemo/trn/v1?param1=AAA HTTP/1.1",
"opcRequestId": "iuZkAC2yJP7FNe3pvMku9A../7F00D1DE5C36BB767D470361AF45220E/5ACE79942327FF60984685C24CE70897",
"remoteAddr": "66.27.72.100",
"requestDuration": 0.002,
"requestMethod": "GET",
"requestUri": "/devcndemo/trn/v1?param1=AAA",
"serverProtocol": "HTTP/1.1",
"status": 403
},
"id": "38752d25-a951-11ed-8250-80ea92ac59f5",
"oracle": {
"compartmentid": "ocid1.tenancy.oc1..aaaaaaaafjw5ox6ux6mjbktsnepxoiwbbbbbk2xcqaaaaaaa",
"ingestedtime": "2023-02-10T14:44:11.180Z",
"loggroupid": "ocid1.loggroup.oc1.iad.amaaaaaamm46asyapdhcorvttttttttl2uoulr737aua",
"logid": "ocid1.log.oc1.iad.amaaaaaamm46asyaqb5cryclp3kdjcc4a6mvyknynyfx7iqda",
"tenantid": "ocid1.tenancy.oc1..aaaaaaaafjw5ox6ux6mjbkaaaaaaenreisot4gnb4bk2bbb"
},
"source": "DEV CNDEMO",
"specversion": "1.0",
"time": "2023-02-10T14:43:02.298Z",
"type": "com.oraclecloud.apigateway.apideployment.access"
}
}
Execution Logs
Execution logs record information about processing within the API gateway for an API deployment. Execution logs include details such as the usage plan that was used, the subscriber id, etc.
Overall API Strategy
If you have other APIs besides ORDS REST Services, API Gateway can provide a single technology to provide public access to all of your APIs. As part of an overall API strategy, API Gateway provides consolidated logging, standard authentication, transformation rules, rate limiting, usage plans, etc. This may make API Gateway appealing, even if your ORDS APIs don't specifically need to use API Gateway.
Conclusion
Hopefully, this post has provided you with enough information to determine if API Gateway is the right service for you.