Creating an API Gateway

• Console
• CLI
• API

• 1. On the Gateways list page, select Create Gateway. If you need help finding the list page, see Listing API Gateways.

  2. Specify the following values for the new API gateway:

     • Name: The name of the API gateway. Avoid entering confidential information.
     • Type: The type of API gateway to create.
       • Select Private if you only want the API gateway (and the APIs deployed on it) to be accessible by resources in the same private network (VCN), or by resources in other private or on-premise networks peered to that private network.
       • Select Public if you want the API gateway (and the APIs deployed on it) to be publicly accessible. Public API gateways can be reached from the internet, provided an internet gateway is present in the API gateway's VCN.
     • Compartment: The compartment in which to create the API gateway.
     • Virtual cloud network in <compartment-name>: The VCN in which to create the API gateway. The VCN can be in the same compartment as the API gateway, but doesn't have to be.
     • Subnet in <compartment-name>: The 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.

       Be aware 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 Already Exist.

     • Enable Network Security Groups: Select this option to control access to and from the API gateway by 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 in addition to, those defined for security lists. NSGs can belong to the same compartment as the new API gateway, but don't have to. See Network Security Groups.
     • Certificate: The TLS certificate that the API gateway uses. The TLS certificate that 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 generated default domain name will contain 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 only available if your tenancy exists in the OC1 realm.
       • Certificates Service category (if shown): Select an existing Certificates service certificate resource that contains the 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 that you select. This category is shown only if Certificates service certificate resources are available in the selected compartment.
       • API Gateway Certificates category (if shown): Select an existing API Gateway certificate resource that contains the 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 shown only if API Gateway certificate resources are available in the selected compartment.

       See Setting Up Custom Domains and TLS Certificates.

       Note
       
       

       We recommend using a custom TLS certificate for public or production systems. We recommend using a default TLS certificate obtained by the API Gateway service only for private or non-production systems (for example, for development and testing).

  3. Optionally, select Show advanced options and specify the following values:
     • 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 or ask an administrator. You can apply tags later.
       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. Apply a defined tag to an API gateway only if the defined tag isn't going to change. If you're not sure whether a defined tag will change, we recommend that you don't apply it to an API gateway.

  4. Select Create Gateway to create the API gateway immediately.

     Be aware 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. When it has been created successfully, the 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 selecting 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.

  5. 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), perform the following actions:

     1. Select the name of the API gateway, and select Work requests to see an overview of the API gateway creation operation.
     2. Select 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 can't diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.

  After you successfully create 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:

     Command

     CopyTry It

     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 only want the API gateway (and the APIs deployed on it) to be accessible by resources in the same private network (VCN), or by resources in other private or on-premise networks peered to that private network. Specify PUBLIC if you want the API gateway (and the APIs deployed on it) to be publicly accessible. Public API gateways can be reached from the internet, provided an internet gateway is present in the API gateway's VCN.
     • <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 Already Exist.

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

     Command

     CopyTry It

     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:

     Command

     CopyTry It

     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:

     Command

     CopyTry It

     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:

     Command

     CopyTry It

     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:

     Command

     CopyTry It

     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:

     Command

     CopyTry It

     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.