Creating an API Resource with an API Description

• Console
• CLI
• API

• 1. Open the navigation menu and click Developer Services. Under API Management, click APIs.
  2. Select a compartment that you have permission to work in.

  3. Click Create API and then specify the following values for the API resource:

     • Name: The name of the API resource. Avoid entering confidential information.
     • Compartment: The compartment in which to create the API resource.
     • Upload API description file: (Optional) A file that contains the API description (in a supported language) to upload and from which to create the API description. The file can be up to 1 MB in size. The file is parsed to confirm that it's 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.
     • Show advanced options: Select this option to apply tags to the resource. 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 API resource.

     If you uploaded an API description file, an API description is created and validated. 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 following actions occur:

     • 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 API resource immediately, you can create it later by using Resource Manager and Terraform. Click 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), follow these steps:

     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 can't diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.

  6. If you didn't upload an API description file when you first created the API resource, or if you subsequently want to upload a different API description file, follow these steps:

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

  After you have 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 using the CLI, follow these steps:

  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.