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.

Console
CLI
API

To create an API resource, optionally with an API description created from an uploaded API description file, using the Console:

In the Console, open the navigation menu and click Developer Services. Under API Management, click Gateways.
Choose a Compartment you have permission to work in.

On the APIs page, click Create API Resource 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.

Click Create 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.

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):

Click Work Requests to see an overview of the API description validation operation.
Click the Validate API operation to see more information about the operation (including error messages, log messages, and the status of associated resources).
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.

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:

On the APIs page, select Edit from the Actions menu beside the API resource.
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).