API Gateway Concepts

This topic describes key concepts you need to understand when using the API Gateway service.

API Gateways

In the API Gateway service, an API gateway is a virtual network appliance in a regional subnet. Private API gateways can only be accessed by resources in the same subnet. Public API gateways are publicly accessible, including from the internet.

An API gateway routes inbound traffic to back-end services including public, private, and partner HTTP APIs, as well as Oracle Functions. Each API gateway is a private endpoint that you can optionally expose over a public IP address as a public API gateway.

To ensure high availability, you can only create API gateways in regional subnets (not AD-specific subnets). You can create private API gateways in private or public subnets, but you can only create public API gateways in public subnets.

An API gateway is bound to a specific VNIC.

You create an API gateway within a compartment in your tenancy. Each API gateway has a single front end, zero or more back ends, and has zero or more APIs deployed on it as API deployments.

APIs

In the API Gateway service, an API is a set of resources, and the methods (for example, GET, PUT) that can be performed on each resource in response to requests sent by a caller (a user or system).

To enable an API gateway to process API requests, you must deploy the API on the API gateway by creating an API deployment.

API Deployments

In the API Gateway service, an API deployment is the means by which you deploy an API on an API gateway. Before the API gateway can handle requests to the API, you must create an API deployment.

When you create an API deployment, you define properties for the API deployment, including an API deployment specification. Every API deployment has an API deployment specification.

You can deploy multiple APIs on the same API gateway, so a single API gateway can host multiple API deployments.

API Deployment Specifications

In the API Gateway service, an API deployment specification describes some aspects of an API deployment.

When you create the API deployment, you define properties for the API deployment, including an API deployment specification. Every API deployment has an API deployment specification. You can create an API deployment specification using dialogs in the Console, or using your preferred JSON editor to create a JSON file.

Each API deployment specification defines one or more back-end resources, the route to each back-end resource, and the methods (for example, GET, PUT) that can be performed on each resource. The API deployment specification describes how the API gateway integrates with the back end to execute those methods. The API deployment specification can also include request and response policies.

Front ends

In the API Gateway service, a front end is the means by which requests flow into an API gateway. An API gateway can have either a public front end or a private front end:

  • A public front end exposes the APIs deployed on an API gateway via a public IP address.
  • A private front end exposes the APIs deployed on an API gateway to a VCN via a private endpoint.

Back ends

In the API Gateway service, a back end is the means by which a gateway routes requests to the back-end services that implement APIs. If you add a private endpoint back end to an API gateway, you give the API gateway access to the VCN associated with that private endpoint.

You can also grant an API gateway access to other Oracle Cloud Infrastructure services as back ends. For example, you could grant an API gateway access to Oracle Functions, so you can create and deploy an API that is backed by a serverless function.

API Callers, API Gateway Developers, and API Gateway Administrators

An API caller is a person or system that calls an API by sending requests to the API gateway on which the API is deployed.

An API Gateway developer is typically a user responsible for creating API deployment specifications and deploying them to API gateways. An API Gateway developer might also create API gateways.

An API Gateway administrator is a person responsible for setting up the API Gateway service. For example, by setting up IAM policies. An API Gateway administrator might also create API gateways.

Routes

In the API Gateway service, a route is the mapping between a path, one or more methods, and a back-end service. Routes are defined in API deployment specifications.

Policies

In the API Gateway service, there are two types of policy:

  • a request policy describes actions to be performed on an incoming request from a caller before it is sent to a back end
  • a response policy describes actions to be performed on a response returned from a back end before it is sent to a caller

You can use request policies to:

  • limit the number of requests sent to back-end services
  • enable CORS (Cross-Origin Resource Sharing) support
  • provide authentication and authorization

You can add request policies to an API deployment specification that apply globally to all routes in the API deployment specification, as well as request policies that apply only to particular routes.

Note the following:

  • No response policies are currently available.
  • API Gateway policies are different to IAM policies, which control access to Oracle Cloud Infrastructure resources.