Creating an API Gateway

You can create one or more API gateways to process traffic from API clients and route it to back-end services. Having created an API gateway, you then deploy an API on the API gateway by creating an API deployment.

You can use a single API gateway as the front end for multiple back-end services by:

  • Creating a single API deployment on the API gateway, with an API deployment specification that defines multiple back-end services.
  • Creating multiple API deployments on the same API gateway, each with an API deployment specification that defines one (or more) back-end services.

Having a single API gateway as a front end enables you to present a single cohesive API to API consumers and API clients, even if the API is actually comprised of smaller microservices written by different software teams using different programming languages or technologies.

Using the Console

To create an API gateway:

  1. In the Console, open the navigation menu and click Developer Services. Under API Management, click Gateways.
  2. Choose a Compartment you have permission to work in.
  3. On the Gateways page, click Create Gateway and specify:

    • Name: The name of the new API gateway. Avoid entering confidential information.
    • Type: The type of API gateway to create. Select Private if you want the API gateway (and the APIs deployed on it) to be accessible only from the same subnet in which the API gateway is created. Select Public if you want the API gateway (and the APIs deployed on it) to be accessible from the internet. In the case of a public API gateway, an internet gateway must exist to give access to the VCN.
    • Compartment: The compartment to which the new API gateway is to belong.
    • Custom DNS: Use this option to determine the TLS certificate (and associated domain name) that the API gateway uses.

      Do not select this option if you want the domain name to be generated automatically for you, and you want the API gateway to use a TLS certificate obtained by the API Gateway service (the default behavior). The auto-generated domain name will comprise a random string of characters followed by .apigateway.<region-identifier>.oci.customer-oci.com. For example, laksjd.apigateway.us-phoenix-1.oci.customer-oci.com .

      Do select this option if you want the API gateway to use a custom TLS certificate (and associated custom domain name). In this case, specify the name of the default API Gateway certificate resource containing details of the custom TLS certificate (and associated custom domain name) that you want the API gateway to use.

      Note that for public or production systems, Oracle recommends using custom TLS certificates. Oracle recommends only using TLS certificates obtained by the API Gateway service for private or non-production systems (for example, for development and testing).

      See Setting Up Custom Domains and TLS Certificates.

    • VCN in <compartment-name>: The VCN in which to create the API gateway. The VCN can belong to the same compartment as the new API gateway, but does not have to.
    • Subnet in <compartment-name>: The name of a public or private regional subnet in which to create the API gateway. If you want to create a public API gateway, you must specify a public regional subnet.
  4. Optionally, click Advanced Options and specify:
    • Response Caching: Options to enable and configure response caching for the API gateway to improve performance and reduce load on back-end services. See Caching Responses to Improve Performance.
    • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.
      Note

      If you apply a defined tag to an API gateway (either directly or as a tag default for a compartment) and subsequently modify the tag definition, the API gateway can enter a failed state. Only apply a defined tag to an API gateway if the defined tag is not going to change. If you are not sure whether a defined tag will change, we recommend you do not apply it to an API gateway.
  5. Click Create to create the new API gateway.

    Note that it can take a few minutes to create the new API gateway. While it is being created, the API gateway is shown with a state of Creating on the Gateways page. When it has been created successfully, the new API gateway is shown with a state of Active.

  6. If you have waited more than a few minutes for the API gateway to be shown with an Active state (or if the API gateway creation operation has failed):

    1. Click the name of the API gateway, and click Work Requests to see an overview of the API gateway creation operation.
    2. Click the Create Gateway operation to see more information about the operation (including error messages, log messages, and the status of associated resources).
    3. If the API gateway creation operation has failed and you cannot diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.

Having successfully created an API gateway, you can deploy an API on it (see Deploying an API on an API Gateway by Creating an API Deployment).

Using the CLI

To create a new API gateway using the CLI:

  1. Configure your client environment to use the CLI (Configuring Your Client Environment to use the CLI for API Gateway Development).
  2. Open a command prompt and run oci api-gateway gateway create to create the API gateway:

    oci api-gateway gateway create --display-name "<gateway-name>" --compartment-id <compartment-ocid> --endpoint-type "<gateway-type>" --subnet-id <subnet-ocid> --certificate-id <certificate-ocid> --response-cache-details file:///<filename>

    where:

    • <gateway-name> is the name of the new API gateway. Avoid entering confidential information.
    • <compartment-ocid> is the OCID of the compartment to which the new API gateway will belong.
    • <gateway-type> is the type of API gateway to create. Specify PRIVATE if you want the API gateway (and the APIs deployed on it) to be accessible only from the same subnet in which the API gateway is created. Specify PUBLIC if you want the API gateway (and the APIs deployed on it) to be accessible from the internet.
    • <subnet-ocid> is the OCID of a public or private regional subnet in which to create the API gateway. If you want to create a public API gateway, you must specify a public regional subnet.
    • <certificate-ocid> (optional) is the OCID of the API Gateway certificate resource created for the API gateway's custom TLS certificate. See Setting Up Custom Domains and TLS Certificates.
    • --response-cache-details file:///<filename> (optional) is the cache configuration file, including a path, to enable and configure response caching. See Caching Responses to Improve Performance.

    For example:

    oci api-gateway gateway create --display-name "Hello World Gateway" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --endpoint-type "PRIVATE" --subnet-id ocid1.subnet.oc1.iad.aaaaaaaaz______rca

    The response to the command includes:

    • The API gateway's OCID.
    • The host name, as the domain name to use when calling an API deployed on the API gateway. If you didn't specify an API Gateway certificate resource when creating the API gateway, a domain name is automatically generated in the format <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.com, where:

      • <gateway-identifier> is a string of characters that identifies the API gateway. For example, lak...sjd (abbreviated for readability).
      • <region-identifier> is the identifier of the region in which the API gateway has been created. See Availability by Region.

      For example, lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com.

    • The lifecycle state (for example, ACTIVE, FAILED).
    • The id of the work request to create the API gateway (details of work requests are available for seven days after completion, cancellation, or failure).

    If you want the command to wait to return control until the API gateway is active (or the request has failed), include either or both the following parameters:

    • --wait-for-state ACTIVE
    • --wait-for-state FAILED

    For example:

    oci api-gateway gateway create --display-name "Hello World Gateway" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --endpoint-type "PRIVATE" --subnet-id ocid1.subnet.oc1.iad.aaaaaaaaz______rca --wait-for-state ACTIVE

    Note that you cannot use the API gateway until the work request has successfully created it and the API gateway is active.

  3. (Optional) To see the status of the API gateway, enter:

    oci api-gateway gateway get --gateway-id <gateway-ocid>
  4. (Optional) To see the status of the work request that is creating the API gateway, enter:

    oci api-gateway work-request get --work-request-id <work-request-ocid>
  5. (Optional) To view the logs of the work request that is creating the API gateway, enter:

    oci api-gateway work-request-log list --work-request-id <work-request-ocid>
  6. (Optional) If the work request that is creating the API gateway fails and you want to review the error logs, enter:

    oci api-gateway work-request-error --work-request-id <work-request-ocid>

For more information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see CLI Help.