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

Last updated: 2021-10-06

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

Short description

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.

Important: To import a REST API, you must also recreate any integrated API resources in the destination account or Region.

Resolution

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

Export the API using either the API Gateway console or AWS CLI

To export an API using the API Gateway console

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.    Based on your use case, pause on one of the following:
Export as Swagger + API Gateway Extensions
Export as OpenAPI 3 + API Gateway Extensions

Your OpenAPI definition appears in the console.

6.    Choose JSON or YAML to download the OpenAPI definition as your preferred file type.

To export an API using the AWS CLI

Run the following get-export command:

Important: Change the values of the command options --parameters, --export-type, and --accept to match your preferred export format.

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

For more information, see Export a REST API from API Gateway. Also, get-export (AWS CLI command reference).

Update the Amazon Resource Names (ARNs) of API resources in your exported OpenAPI definition

Change the ARNs of API resources in your OpenAPI definition to the resource ARNs in the account and Region the API is migrating to.

Example snippet of a Swagger template for an API with AWS Lambda integrations

Important: To use this snippet, 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.

"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"
            }
          }

Import the API to API Gateway in another account or Region

To import an API using the API Gateway console

1.    Open the API Gateway console in the destination account or Region.

2.    Choose Create API.

3.    Under REST API, for Choose an API type, 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.
-or-
Paste your updated OpenAPI definition into the text editor field.

5.    Under Settings, for Endpoint Type, choose one of the following based on your use case:
Regional
Edge optimized

Private

6.    Choose Fail on warnings to stop importing if there's an error or warning during import. Or, choose Ignore warnings to import the API whether there's an error or warning during import or not.

To import an API using the AWS CLI

1.    Configure the AWS CLI for the destination account or Region.

2.    Run the following import-rest-api command:

$ 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?


Do you need billing or technical support?