Creating an API Gateway

• Console
• CLI
• API

• 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.
     • 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.

       Note that API Gateway communicates on port 443, which is not open by default. You have to add a new stateful ingress security rule for the regional subnet (either in a security list or in a network security group) to allow traffic on port 443. For the properties of the ingress security rule, see Create a VCN to Use with API Gateway, if one doesn't exist already.

     • Certificate: Select the TLS certificate that the API gateway uses. The TLS certificate you select determines the API gateway's domain name:
       • Default (*.oci.customer-oci.com) (if shown): Select this option if you want the domain name to be generated automatically for you, and you want the API gateway to use a default TLS certificate obtained by the API Gateway service. The auto-generated default 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. This option is not available in some regions.
       • Certificates Service category (if shown): Select an existing Certificates service certificate resource containing details of the custom TLS certificate that you want the API gateway to use. The API gateway uses a custom domain name associated with the certificate you select. This category is only shown if Certificates service certificate resources are available in the selected compartment.
       • API Gateway Certificates category (if shown): Select an existing API Gateway certificate resource containing details of the custom TLS certificate that you want the API gateway to use. The API gateway uses a custom domain name associated with the certificate you select. This category is only shown if API Gateway certificate resources are available in the selected compartment.

       Note that for public or production systems, Oracle recommends using custom TLS certificates. Oracle recommends only using a default TLS certificate 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.

     • Enable Network Security Groups: Use this option to control access to and from the API gateway using security rules defined for one or more network security groups (NSGs) that you specify (up to a maximum of five network security groups). You can use security rules defined for NSGs instead of, or as well as, those defined for security lists. NSGs can belong to the same compartment as the new API gateway, but do not have to. See Network Security Groups.
  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.
     • Certificate Authorities: One or more Certificate Authority (CA) resources or CA bundle resources to add to the API gateway's trust store as custom CAs and custom CA bundles (in addition to the default CA bundle). Custom CAs and custom CA bundles are used to verify TLS certificates presented by API clients and back-end services. See Customizing Trust Stores for TLS Certificate Verification.
     • 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're not sure whether to apply tags, skip this option (you can apply tags later) or ask an 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.

     Also note that rather than creating the new API gateway immediately, you can create it later using Resource Manager and Terraform, by clicking Save as stack to save the resource definition as a Terraform configuration. For more information about saving stacks from resource definitions, see Creating a Stack from a Resource Creation Page.

  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).

• 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> --ca-bundles file:///<filename> --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.

       Note that API Gateway communicates on port 443, which is not open by default. You have to add a new stateful ingress security rule for the regional subnet (either in a security list or in a network security group) to allow traffic on port 443. For the properties of the ingress security rule, see Create a VCN to Use with API Gateway, if one doesn't exist already.

     • --network-security-group-ids <nsg-ocids> (optional) is the OCID of one or more network security groups. The value of <nsg-ocids> must be in valid JSON format (either as a string, or passed in as a file using the file:///<filename> syntax including a path).
     • <certificate-ocid> (optional) is the OCID of the certificate resource created for the API gateway's custom TLS certificate (either an API Gateway certificate resource or a Certificates service certificate resource). See Setting Up Custom Domains and TLS Certificates.
     • --ca-bundles file:///<filename> (optional) is a file containing details of one or more Certificate Authority (CA) resources or CA bundle resources to add to the API gateway's trust store as custom CAs and custom CA bundles (in addition to the default CA bundle). Custom CAs and custom CA bundles are used to verify TLS certificates presented by API clients and back-end services. See Customizing Trust Stores for TLS Certificate Verification.
     • --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 a 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.

• Run the CreateGateway operation to create an API gateway.