Skip to main content Skip to complementary content

Updating an API definition on AWS API Gateway

Import a JSON file to AWS API Gateway to update an existing definition.

Before you begin

  • You have access to AWS API Gateway.
  • You have installed AWS CLI. For more information, see Installing the AWS CLI.
  • You have exported your API definition as a JSON file.
  • You have uploaded a previous version of the API definition to AWS API Gateway.


  1. Open a command line and enter the following command to upload the file:
    aws apigateway put-rest-api --rest-api-id {api-id} --mode {mode} --body 'file://{yourfile}.json'
  2. Add the correct parameters:
    Parameter Description
    {api-id} AWS API Gateway ID of the API to update.
    {mode} Behavior at import. The value can be either overwrite to replace the previous version of the API with the new one, or merge to merge the two versions.
    {yourfile} Path and file name of the API definition you exported.
  3. Execute the command.


Your API definition is merged or overwritten, depending on the mode you defined. You can check your update on the AWS API Gateway console.

In this example, a first version of the API definition containing only the /contacts resource and its operations was uploaded. Then, a second version with the /companies resource was uploaded and merged with the previous version.

Screenshot of the merged API definition.

For more information about the put-rest-api command, see the AWS documentation.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – let us know how we can improve!