Updating API Gateways and API Deployments

Having created an API gateway, and deployed an API on the API gateway by creating an API deployment, you might decide to change either or both. For example, to change the API gateway's name or the tags applied to it, or to change an API deployment specification to add additional back ends to the API deployment.

Note that there are some properties of API gateways and API deployments for which you cannot change the original values.

You can update API gateways and API deployments using the Console, the CLI, and the API.

You can update an API deployment specification by:

  • using dialogs in the Console
  • editing a JSON file

Using the Console

To update an existing API gateway or an API deployment using the Console:

  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 the name of the API gateway that you want to update (or that contains the API deployment you want to update) to show the Gateway Details page.
  4. To update an API gateway:

    • Click Edit to:
      • Change the API gateway's name. Avoid entering confidential information.
      • Enable or disable the use of network security groups (NSGs) to control access to and from the API gateway, using security rules defined for the 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 API gateway, but do not have to. See Network Security Groups.
      • Change the API Gateway certificate resource used by the API gateway if you have set up a custom TLS certificate (and associated custom domain name). See Setting Up Custom Domains and TLS Certificates.
      • Change response cache configuration settings. See Caching Responses to Improve Performance.
    • Click Move Resource to move the API gateway to a different compartment.
    • Click Add Tag(s) and View Tag(s) to change and view the tags applied to the API gateway.
  5. To update an API deployment, on the Gateway Details page, select Deployments from the Resources list and click the Actions icon (three dots) beside the API deployment you want to update:

    • Click Edit to change the API deployment's name, or to replace the original API deployment specification. You can change the original API deployment specification by selecting one of two options:

      • From Scratch: Select to change API deployment specification properties using dialogs in the Console.
      • Upload an existing API: Select to change API deployment specification properties by uploading a replacement JSON file.

      For more information about defining API deployment specifications, see Creating an API Deployment Specification. Avoid entering confidential information.

    • Click Move Resource to move the API deployment to a different compartment.
    • Click Add Tag(s) and View Tag(s) to change and view the tags applied to the API deployment.

Using the CLI

To update existing API gateways and API deployments 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. To update an existing API gateway:

    1. Open a command prompt and run oci api-gateway gateway update to update the API gateway:

      oci api-gateway gateway update --gateway-id <gateway-ocid> --<property-to-update> <property-value>

      where:

      • <gateway-ocid> is the OCID of the API gateway to update. To find out the API gateway's OCID, see Listing API Gateways and API Deployments.
      • <property-to-update> is the property to update. Note that you can only change the values for display-name, --response-cache-details, --network-security-group-ids, freeform-tags and defined-tags (and certificate-id> if this was originally set for the API gateway). All other values must be identical to values in the original gateway definition.
      • <property-value> is the new value of the property you want to change.

      For example:

      oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --display-name "Hello World Gateway - version 2"

      The response to the command includes:

      • The lifecycle state (for example, ACTIVE, FAILED).
      • The id of the work request to update 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 update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --display-name "Hello World Gateway - version 2" --wait-for-state ACTIVE
    2. (Optional) To see the status of the work request that is updating the API gateway, enter:

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

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>
    4. (Optional) If the work request that is updating 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>
    5. (Optional)  To verify that the API gateway has been updated, enter the following command and confirm that the API gateway's properties are as you expect:

      oci api-gateway gateway get --gateway-id <gateway-ocid>
  3. To update an existing API deployment:

    1. Open a command prompt and run oci api-gateway deployment update to update the API deployment:

      oci api-gateway deployment update --deployment-id <deployment-ocid> --specification file:///<filename>

      where:

      • <deployment-ocid> is the OCID of the API deployment to update. To find out the API deployment's OCID, see Listing API Gateways and API Deployments.
      • <filename> is the relative location and filename of the JSON file containing the replacement API deployment specification. For example, replacement-specification.json. For more information about defining API deployment specifications, see Creating an API Deployment Specification.

      For example:

      oci api-gateway deployment update --deployment-id ocid1.apideployment.oc1..aaaaaaaaab______pwa --specification file:///Users/jdoe/work/replacement-specification.json

      The response to the command includes:

      • The lifecycle state (for example, ACTIVE, FAILED).
      • The id of the work request to update 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 update --deployment-id ocid1.apideployment.oc1..aaaaaaaaab______pwa --specification file:///Users/jdoe/work/replacement-specification.json --wait-for-state ACTIVE
    2. (Optional) To see the status of the work request that is updating the API deployment, enter:

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

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>
    4. (Optional) If the work request that is updating 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>
    5. (Optional)  To verify that the API deployment has been updated, enter the following command and confirm that the API deployment's properties are as you expect:

      oci api-gateway deployment get --deployment-id <deployment-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.