Deploying an API on an API Gateway by Creating an API Deployment

Having created an API gateway, you deploy an API on the API gateway by creating an API deployment. When you create an API deployment, you include an API deployment specification that defines the API. The API Gateway service inspects the API deployment specification to confirm that it is valid.

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.

Using the Console to Create an API Deployment from Scratch

To use the Console to create an API deployment, entering the API deployment specification in dialogs in the Console as you go:

  1. In the Console, open the navigation menu. Under Solutions and Platform, go to Developer Services and click API Gateway.
  2. Choose a Compartment you have permission to work in.
  3. On the Gateways page, click the name of the API gateway on which you want to deploy the API to show the Gateway Details page.
  4. On the Gateway Details page, select Deployments from the Resources list, and then click Create Deployment.
  5. Click From Scratch and in the Basic Information section, specify:

    • Name: The name of the new API deployment. Avoid entering confidential information.
    • Path Prefix: A path on which to deploy all routes contained in the API deployment specification. For example:

      • /v1
      • /v2
      • /test/20191122

      Note that the deployment path prefix you specify:

      • must be preceded by a forward slash ( / )
      • can contain multiple forward slashes (provided they are not adjacent), but must not end with a forward slash
      • can include alphanumeric uppercase and lowercase characters
      • can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
      • cannot include parameters and wildcards
    • Compartment: The compartment in which to create the new API deployment.
  6. (Optional) In the API Request Policies section, optionally specify request policy details to provide support for:

  7. (Optional) In the API Logging Policies section, optionally specify logging policy details for an:

    • Access Log: Whether to record a summary of every request and response that goes through the gateway.
    • Execution Log: Whether to record information about processing within the API gateway.

    See Adding Logging Policies to API Deployment Specifications.

  8. (Optional) Click Show Advanced Options and optionally specify:

    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, 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 if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  9. Click Next to enter details of the routes in the API deployment.
  10. In the Route 1 section, specify the first route in the API deployment that maps a path and one or more methods to a back-end service:

    • Path: A path for API calls using the listed methods to the back-end service. Note that the route path you specify:

      • is relative to the deployment path prefix
      • must be preceded by a forward slash ( / ), and can be just that single forward slash
      • can contain multiple forward slashes (provided they are not adjacent), and can end with a forward slash
      • can include alphanumeric uppercase and lowercase characters
      • can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
      • can include parameters and wildcards (see Adding Path Parameters and Wildcards to Route Paths)
    • Methods: One or more methods accepted by the back-end service, separated by commas. For example, GET, PUT.
    • Type: The type of the back-end service, as one of:
  11. (Optional) Click Another Route to enter details of additional routes.
  12. Click Next to review the details you entered for the new API deployment.
  13. Click Create to create the new API deployment.

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

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

    1. Click the name of the API deployment, and click Work Requests to see an overview of the API deployment creation operation.
    2. Click the Create Deployment operation to see more information about the operation (including error messages, log messages, and the status of associated resources).
    3. If the API deployment creation operation has failed and you cannot diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.
  15. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

Using the Console to Create an API Deployment from a JSON File

To use the Console to create an API deployment, uploading the API deployment specification from a JSON file:

  1. In the Console, open the navigation menu. Under Solutions and Platform, go to Developer Services and click API Gateway.
  2. Choose a Compartment you have permission to work in.
  3. On the Gateways page, click the name of the API gateway on which you want to deploy the API to show the Gateway Details page.
  4. On the Gateway Details page, select Deployments from the Resources list, and then click Create Deployment.
  5. Click Upload an existing API.
  6. In the Upload Information section, specify:

    • Name: The name of the new API deployment. Avoid entering confidential information.
    • Path Prefix: A path on which to deploy all routes contained in the API deployment specification. For example:

      • /v1
      • /v2
      • /test/20191122

      Note that the deployment path prefix you specify:

      • must be preceded by a forward slash ( / )
      • can contain multiple forward slashes (provided they are not adjacent), but must not end with a forward slash
      • can include alphanumeric uppercase and lowercase characters
      • can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
      • cannot include parameters and wildcards
    • Compartment: The compartment in which to create the new API deployment.
    • Specification: The JSON file containing the API deployment specification, either by dragging and dropping the file, or by clicking select one. See Creating an API Deployment Specification.
  7. (Optional) Click Show Advanced Options and optionally specify:

    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, 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 if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  8. Click Next to review the details you entered for the new API deployment.
  9. Click Create to create the new API deployment.

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

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

    1. Click the name of the API deployment, and click Work Requests to see an overview of the API deployment creation operation.
    2. Click the Create Deployment operation to see more information about the operation (including error messages, log messages, and the status of associated resources).
    3. If the API deployment creation operation has failed and you cannot diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.
  11. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

Using the CLI

To create a new API deployment 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 deployment create to create the deployment:

    oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name> --gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification file:///<filename>
    

    where:

    • <compartment-ocid> is the OCID of the compartment in which to create the new API deployment.
    • <api-name> is the name of the new API deployment. Avoid entering confidential information.
    • <gateway-ocid> is the OCID of the existing gateway on which to deploy the API. To find out the API gateway's OCID, see Listing API Gateways and API Deployments.
    • /<deployment-path-prefix> is a path on which to deploy all routes contained in the API deployment specification.

      Note that the deployment path prefix you specify:

      • must be preceded by a forward slash ( / ) in the JSON file
      • can contain multiple forward slashes (provided they are not adjacent), but must not end with a forward slash
      • can include alphanumeric uppercase and lowercase characters
      • can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
      • cannot include parameters and wildcards
    • <filename> is the API deployment specification, including a path, one or more methods, and a back end definition. See Creating an API Deployment Specification.

    For example:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json

    The response to the command includes:

    • The API deployment's OCID.
    • The host name on which the API deployment has been created, as a domain name in the format <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.com, where:

      • <gateway-identifier> is the 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 deployment has been created. See Availability by Region.

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

      The host name will be the domain name to use when calling an API deployed on the API gateway.

    • The lifecycle state (for example, ACTIVE, FAILED).
    • The id of the work request to create the API deployment (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 deployment 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 deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state ACTIVE

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

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

    oci api-gateway deployment get --deployment-id <deployment-ocid>
  4. (Optional) To see the status of the work request that is creating the API deployment, 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 deployment, 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 deployment 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.