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

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 you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Export the API

To export the API, you can use either the API Gateway console or the AWS CLI.

Use the API Gateway console

To export an API from the API Gateway console, complete the following steps:

1. In the API Gateway console, choose your API.
2. Deploy your API to a stage.
3. In the Stage Editor pane, choose Stage Actions, and then choose Export.
4. For API specification type, choose Swagger or OpenAPI3.
5. For Format, choose either JSON or YAML based on your preferred file type for the OpenAPI definition download.
6. For Extensions, choose one of the following:
   Export without extensions
   Export with API Gateway extensions
   Export with Postman extensions
7. Choose Export API.

Use the AWS CLI

To export an API from 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.

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

Change the Amazon Resource Name (ARN) of the API resources in your OpenAPI definition to the resource ARNs in the account and Region where you want to migrate the API to.

See the following 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

You can use either the API Gateway console or the AWS CLI to import an API to another account or Region.

Use the API Gateway console

To import an API from the API Gateway console, complete the following steps:

1. Open the API Gateway console in the destination account or Region.
2. Choose Create API.
3. Under REST API, choose Import.
4. Under API definition, 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 API endpoint type, choose one of the following:
   Regional
   Edge optimized
   Private
6. Choose Fail on warnings to stop importing when there's an error or warning during import. Or, choose Ignore warnings to import the API when there's an error or warning during import.

Use the AWS CLI

To import an API from the AWS CLI, complete the following steps:

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'

Related information

Develop REST APIs using OpenAPI in API Gateway

Tutorial: Create a REST API by importing an example