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

Last updated: 2020-12-17

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

Short description

To migrate your Amazon API Gateway API between AWS accounts or Regions, 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 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

Use either the API Gateway console or the 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. Your OpenAPI definition will appear in the console. Then, choose JSON or YAML to download the OpenAPI definition as your preferred file type.

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

Example get-export command

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

Important: Make sure that you change the values of the command options --parameters, --export-type, and --accept to match your preferred export format. For more information, see get-export (AWS CLI command reference) and 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?


Do you need billing or technical support?