Creating an API Resource with an API Description

Find out how to create an API resource with the API Gateway service that you can use to deploy an API on an API gateway.

When using the API Gateway service, you have the option to create an API resource. You can use the API resource to deploy an API on an API gateway. The API resource has an API description that describes the API.

If you use an API resource to deploy an API on an API gateway, its API description pre-populates some of the properties of the API deployment specification.

You import the API description from a file (sometimes called an 'API specification', or 'API spec') written in a supported language. Currently, OpenAPI Specification version 2.0 (formerly Swagger Specification 2.0) and version 3.0 are supported.

Note that creating an API resource in the API Gateway service is optional. You can deploy an API on an API gateway without creating an API resource in the API Gateway service. Note also that you can create an API resource that doesn't have an API description initially, and then add an API description later.

  • To create an API resource, optionally with an API description created from an uploaded API description file, 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 APIs page, click Create API and specify:

      • Name: The name of the new API resource. Avoid entering confidential information.
      • Compartment: The compartment to which the new API resource is to belong.
      • Upload API Description File: (optional) A file containing an API description (in a supported language) to upload and from which to create the API description. The file can be up to 1MB in size. The file is parsed to confirm that it is in a supported language and correctly formatted. Currently, OpenAPI Specification version 2.0 (formerly Swagger Specification 2.0) and version 3.0 files are supported.
      • 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.
    4. Click Create API to create the new API resource.

      If you uploaded an API description file, an API description is created and validated. Note that it can take a few minutes to validate the API description. While it is being validated, the API description is shown with a state of Validating on the Validations page. When the API description has been validated successfully:

      • The Validations page shows successful validation.
      • The API description page shows the API description created from the API description file.
      • The API Deployment Specification page shows any additional information about the default API deployment specification created from the API description.

      Note that rather than creating the new API resource 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.

    5. If you have waited more than a few minutes for the API description to be shown as Valid (or if the API description validation operation has failed):

      1. Click Work Requests to see an overview of the API description validation operation.
      2. Click the Validate API operation to see more information about the operation (including error messages, log messages, and the status of associated resources).
      3. If the API description validation operation has failed and you cannot diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.
    6. If you don't upload an API description file when you first create an API resource, or if you subsequently want to upload a different API description file:

      1. On the APIs page, select Edit from the Actions menu (Actions Menu) beside the API resource.
      2. Provide details of the API description file from which to create the API description.

    Having successfully created an API resource with an API description, you can deploy it on an API gateway (see Using the Console to Create an API Deployment from an API Resource).

  • To create an API resource, optionally with an API description created from an uploaded API description file, 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 api create to create the API resource:
      oci api-gateway api create --display-name "<api-name>" --compartment-id <compartment-ocid> --content "<api-description>"

      where:

      • <api-name> is the name of the new API resource. Avoid entering confidential information.
      • <compartment-ocid> is the OCID of the compartment to which the new API resource will belong.
      • <api-description> is optionally an API description (in a supported language). The value you specify for <api-description> can be:
        • The entire API description, enclosed within double quotes. Inside the description, each double quote must be escaped with a backslash (\) character. For example (and abbreviated for readability), --content "swagger:\"2.0\",title:\"Sample API\",..."
        • The name and location of an API description file, enclosed within double quotes and in the format "$(< <path>/<filename>.yaml)". For example, --content "$(< /users/jdoe/api.yaml)"
        The description is parsed to confirm that it is in a supported language and correctly formatted. Currently, OpenAPI Specification version 2.0 (formerly Swagger Specification 2.0) and version 3.0 files are supported.

      For example:

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..."

      The response to the command includes:

      • The API resource's OCID.
      • The lifecycle state (for example, SUCCEEDED, FAILED).
      • The id of the work request to create the API resource (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 resource has been created (or the request has failed), include either or both the following parameters:

      • --wait-for-state SUCCEEDED
      • --wait-for-state FAILED

      For example:

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..." --wait-for-state SUCCEEDED

      Note that you cannot use the API resource until the work request has successfully created it.

    3. (Optional) To see the status of the work request that is creating the API resource, enter:

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

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>
    5. (Optional) If the work request that is creating the API resource 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 CreateAPI operation to create an API resource.