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 an execution log level to record information about processing within the API gateway. See Adding Logging to API Deployments.

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

    • 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, then 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: 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, then 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 Console to Create an API Deployment from an API Resource

You can create an API deployment from an existing API resource, using the API resource's API description. In this case, the API description is based on an API description file you've uploaded for the API resource (see Creating an API Resource with an API Description). The API description file provides some initial values for the API deployment specification, which you can modify and extend when creating the API deployment. In particular, a default route is created for each path and associated method in the API description.

To use the Console to create an API deployment from an existing API resource, using an API deployment specification derived from an API description 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 APIs page, click the name of the API resource that you want to deploy.
  4. (Optional) On the API Details page, select API Deployment Specification from the Resources list to confirm that a valid API deployment specification has been created for the API resource from an uploaded API description file. If no API deployment specification is available, see Creating an API Resource with an API Description
  5. On the API Details page, click Deploy API Gateway to use the Console dialogs for creating an API deployment.

    Some of the initial values for the API deployment specification properties shown in the Console dialogs are derived from the API description file.

    The API Information section shows details about the API resource from which to create the API deployment.

  6. In the Gateway section, select the API gateway on which to create the API deployment. If a suitable API gateway does not already exist, click Create Gateway to create one (see Creating an API Gateway).
  7. 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.
  8. (Optional) In the API Request Policies section, optionally specify request policy details to provide support for:

  9. (Optional) In the API Logging Policies section, optionally specify an execution log level to record information about processing within the API gateway. See Adding Logging to API Deployments.

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

    • 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, then skip this option (you can apply tags later) or ask your administrator.
  11. Click Next to review and enter details of the routes in the API deployment.

    By default, a route is created for every path and associated method that is present in the API description. Initially, each of these default routes is created with a stock response back end. The HTTP status code, the content in the body of the response body content, and the header are obtained from the details in the API description. If the API description does not include response information for a particular path and associated method, a default stock response back end is created for that route with 501 as the HTTP status code.

  12. Review each default route in turn, modifying its configuration if necessary to meet your requirements, and adding request, response, and logging policies:

    • 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:
    • Show Route Request Policies: and Show Route Response Policies: Review and optionally update the request policies and response policies that apply to the route. See Adding Request Policies and Response Policies to API Deployment Specifications.
    • Show Route Logging Polices: Review and optionally update the logging policy that applies to the route. See Adding Logging to API Deployments.
  13. (Optional) Click Another Route to enter details of more routes, in addition to those created by default from the API description.
  14. Click Next to review the details you entered for the new API deployment.
  15. 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.

  16. 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.
  17. (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.