How do I migrate API Gateway APIs between AWS accounts or Regions?

Last updated: 2019-12-20

I want to migrate my Amazon API Gateway API between AWS accounts or Regions. How do I do that?

Short Description

You can export a REST API from API Gateway to an OpenAPI 2.0 (Swagger) or OpenAPI 3.0 definition file. Then, import the API to API Gateway in another account or Region.

Note: To successfully import the API, you must also recreate any integrated API resources in the destination account or Region.

Resolution

Export the API

Use either the API Gateway console or the AWS Command Line Interface (AWS CLI) to export your API.

  1. In the API Gateway console, choose your API.
  2. Deploy your API to a stage.
  3. In the Stage Editor pane, choose the Export tab.
  4. For Export as, choose Swagger or OpenAPI3.
  5. Depending on your choice in the previous step, pause on either of the following:
    Export as Swagger + API Gateway Extensions
    Export as OpenAPI 3 + API Gateway Extensions
  6. Choose JSON or YAML. Your OpenAPI definition appears in the Console, and a definition file automatically begins to download.

Or, in the AWS CLI use the get-export command. For example:

$ aws apigateway get-export --parameters extensions='integrations' --rest-api-id a1b2c3d4e5 --stage-name dev --export-type swagger /path/to/filename.json

This example command returns a JSON Swagger template with API Gateway extensions for a stage. Change the values of the command options --parameters and --export-type to export with your preferred properties and type.

For more information, see Export a REST API from API Gateway.

Change the resource ARNs in your OpenAPI definition

Update the Amazon Resource Names (ARNs) of API resources in your exported OpenAPI definition. Change them to resources in the AWS account and Region where you want to migrate. For example, see the following snippet of a Swagger template for an API with AWS Lambda integrations:

"x-amazon-apigateway-integration": {
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:12345678910:function:mylambda/invocations",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          }

In this example, replace arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:12345678910:function:mylambda/invocations with the ARN of a Lambda function in the destination account.

Import the API

After updating the ARNs of your API resources offline, import the OpenAPI definition into API Gateway in your other AWS account or Region.

  1. Open the API Gateway console in the destination AWS account or Region.
  2. Choose Create API.
  3. For Choose an API type, under REST API, choose Import.
  4. Under Import from Swagger or Open API 3, do either of the following:
    Choose Select Swagger File, then choose your updated OpenAPI definition file.
    Paste your updated OpenAPI definition into the text editor field.
  5. Under Settings, for Endpoint Type, choose Regional, Edge optimized, or Private.
  6. Choose Fail on warnings to stop importing if there's an error or warning during import. Or, choose Ignore warnings to import regardless.

Or, configure the AWS CLI for the destination AWS account or Region, and then use the import-rest-api command. For example:

$ aws apigateway import-rest-api --endpointConfigurationTypes 'REGIONAL' --fail-on-warnings --body 'file:/// path/to/filename.json'

For more information, see Import a REST API into API Gateway.


Did this article help you?

Anything we could improve?


Need more help?