Menu
Amazon API Gateway
Developer Guide

Import an API into API Gateway

You can use the API Gateway Import API feature to import an API from an external definition file into API Gateway. Currently, the Import API feature supports Swagger v2.0 definition files.

With the Import API, you can either create a new API by submitting a POST request that includes a definition as the payload, or you can update an existing API by using a PUT request that contains a definition in the payload. You can update an API by overwriting it with a new definition, or merge a definition with an existing API. You specify the options in the request URL using a mode query parameter.

Note

For RAML API definitions, you can continue to use API Gateway Importer.

Besides making explicit calls to the REST API, as described below, you can also use the Import API feature in the API Gateway console. The option is available as an item in the Actions drop-down menu. For an example of using the Import API feature from the API Gateway console, see Build an API Gateway API from an Example.

Use the Import API to Create a New API

To use the Import API feature to create a new API, POST your API definition file to https://apigateway.<region>.amazonaws.com/restapis?mode=import. This request results in a new RestApi, along with Resources, Models, and other items defined in the definition file.

The following code snippet shows an example of the POST request with the payload of a JSON-formatted Swagger definition:

Copy
POST /restapis?mode=import Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ... Swagger API definition in JSON

Use the Import API to Update an Existing API

You can use the Import API feature to update an existing API when there are aspects of that API you would like to preserve, such as stages and stage variables, or references to the API from API Keys.

An API update can occur in two modes: merge or overwrite. Merging an API is useful when you have decomposed your external API definitions into multiple, smaller parts and only want to apply changes from one of those parts at a time. For example, this might occur if multiple teams are responsible for different parts of an API and have changes available at different rates. In this mode, items from the existing API that are not specifically defined in the imported definition will be left alone.

Overwriting an API is useful when an external API definition contains the complete definition of an API. In this mode, items from an existing API that are not specifically defined in the imported definition will be deleted.

To merge an API, submit a PUT request to https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=merge. The restapi_id path parameter value specifies the API to which the supplied API definition will be merged.

The following code snippet shows an example of the PUT request to merge a Swagger API definition in JSON, as the payload, with the specified API already in API Gateway.

Copy
PUT /restapis/<restapi_id>?mode=merge Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ... A Swagger API definition in JSON

The merging update operation takes two complete API definitions and merges them together. For a small and incremental change, you can use the resource update operation.

To overwrite an API, submit a PUT request to https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=overwrite. The restapi_id path parameter specifies the API that will be overwritten with the supplied API definitions.

The following code snippet shows an example of an overwriting request with the payload of a JSON-formatted Swagger definition:

Copy
PUT /restapis/<restapi_id>?mode=overwrite Host:apigateway.<region>.amazonaws.com Content-Type: application/json Content-Length: ... A Swagger API definition in JSON

When the mode query parameter is not specified, merge is assumed.

Note

The PUT operations are idempotent, but not atomic. That means if a system error occurs part way through processing, the API can end up in a bad state. However, repeating the operation will put the API into the same final state as if the first operation had succeeded.

Swagger basePath

In Swagger, you can use the basePath property to provide one or more path parts that precede each path defined in the paths property. Because API Gateway has several ways to express a resource’s path, the Import API feature provides three options for interpreting the basePath property during an import:

ignore

If the Swagger file has a basePath value of "/a/b/c" and the paths property contains "/e" and "/f", the following POST or PUT request:

Copy
POST /restapis?mode=import&basepath=ignore
Copy
PUT /restapis/api_id?basepath=ignore

will result in the following resources in the API:

  • /

  • /e

  • /f

The effect is to treat the basePath as if it was not present, and all of the declared API resources are served relative to the host. This can be used, for example, when you have a custom domain name with an API mapping that does not include a Base Path and a Stage value that refers to your production stage.

Note

API Gateway will automatically create a root resource for you, even if it is not explicitly declared in your definition file.

When unspecified, basePath takes ignore by default.

prepend

If the Swagger file has a basePath value of "/a/b/c" and the paths property contains "/e" and "/f", the following POST or PUT request:

Copy
POST /restapis?mode=import&basepath=prepend
Copy
PUT /restapis/api_id?basepath=prepend

will result in the following resources in the API:

  • /

  • /a

  • /a/b

  • /a/b/c

  • /a/b/c/e

  • /a/b/c/f

The effect is to treat the basePath as specifying additional resources (without methods) and to add them to the declared resource set. This can be used, for example, when different teams are responsible for different parts of an API and the basePath could reference the path location for each team's API part.

Note

API Gateway will automatically create intermediate resources for you, even if they are not explicitly declared in your definition.

split

If the Swagger file has a basePath value of "/a/b/c" and the paths property contains "/e" and "/f", the following POST or PUT request:

Copy
POST /restapis?mode=import&basepath=split
Copy
PUT /restapis/api_id?basepath=split

will result in the following resources in the API:

  • /

  • /b

  • /b/c

  • /b/c/e

  • /b/c/f

The effect is to treat top-most path part, "/a", as the beginning of each resource's path, and to create additional (no method) resources within the API itself. This could, for example, be used when "a" is a stage name that you want to expose as part of your API.

Errors during Import

During the import, errors can be generated for major issues like an invalid Swagger document. Errors are returned as exceptions (e.g., BadRequestException) in an unsuccessful response. When an error occurs, the new API definition is discarded and no change is made to the existing API.

Warnings during Import

During the import, warnings can be generated for minor issues like a missing model reference. If a warning occurs, the operation will continue if the failonwarnings=false query expression is appended to the request URL. Otherwise, the updates will be rolled back. By default, failonwarnings is set to false. In such cases, warnings are returned as a field in the resulting RestApi resource. Otherwise, warnings are returned as a message in the exception.