Amazon API Gateway REST API Reference

restapi:put

Update the definition of a REST API, including the resources, methods, templates, and models.

HTTP Request

PUT /restapis/{restapi_id}{?mode,failonwarnings}

Template Variable

Request Body

// raw byte array representing the api definition

Response

RestApi

Remarks

The update can be a merging or overwriting process. The choice is specified using the mode query parameter.

Example: Merge a supplied Swagger API definition with an existing API

Request

The following example request merges an otherwise standalone API integrated with AWS Lambda through two child resources under the root into an existing API integrated with Amazon S3 through the root resource.

PUT /restapis/wn611yeyp3?mode=merge HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160607T154932Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160607/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}

{
  "swagger": "2.0",
  "info": {
    "version": "2016-06-07T15:48:21Z",
    "title": "HelloWorld"
  },
  "host": "vys2gggws7.execute-api.us-east-1.amazonaws.com",
  "basePath": "/test",
  "schemes": [
    "https"
  ],
  "paths": {
    "/gello": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestTemplates": {
            "application/json": "{}"
          },
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:GetHelloWorld/invocations",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      },
      "post": {
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:GetHelloWorldName/invocations",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    },
    "/hello": {
      "get": {
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            },
            "headers": {
              "Access-Control-Allow-Origin": {
                "type": "string"
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Access-Control-Allow-Origin": "'*'"
              }
            }
          },
          "uri": "https://example.com",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "GET",
          "type": "http"
        }
      },
      "options": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            },
            "headers": {
              "Access-Control-Allow-Origin": {
                "type": "string"
              },
              "Access-Control-Allow-Methods": {
                "type": "string"
              },
              "Access-Control-Allow-Headers": {
                "type": "string"
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Access-Control-Allow-Methods": "'GET,OPTIONS'",
                "method.response.header.Access-Control-Allow-Headers": "'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'",
                "method.response.header.Access-Control-Allow-Origin": "'*'"
              }
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match",
          "type": "mock"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object"
    }
  }
}
Response

The successful response returns 200 OK status and a payload as follows:

{
  "_links": {
    "curies": [
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-authorizer-{rel}.html",
        "name": "authorizer",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-deployment-{rel}.html",
        "name": "deployment",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-model-{rel}.html",
        "name": "model",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-resource-{rel}.html",
        "name": "resource",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-restapi-{rel}.html",
        "name": "restapi",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-stage-{rel}.html",
        "name": "stage",
        "templated": true
      }
    ],
    "self": {
      "href": "/restapis/wn611yeyp3"
    },
    "authorizer:by-id": {
      "href": "/restapis/wn611yeyp3/authorizers/{authorizer_id}",
      "templated": true
    },
    "authorizer:create": {
      "href": "/restapis/wn611yeyp3/authorizers"
    },
    "deployment:by-id": {
      "href": "/restapis/wn611yeyp3/deployments/{deployment_id}{?embed}",
      "templated": true
    },
    "deployment:create": {
      "href": "/restapis/wn611yeyp3/deployments"
    },
    "model:by-name": {
      "href": "/restapis/wn611yeyp3/models/{model_name}?flatten=false",
      "templated": true
    },
    "model:create": {
      "href": "/restapis/wn611yeyp3/models"
    },
    "resource:by-id": {
      "href": "/restapis/wn611yeyp3/resources/{resource_id}{?embed}",
      "templated": true
    },
    "resource:create": {
      "href": "/restapis/wn611yeyp3/resources/s3dmsjgijc"
    },
    "restapi:authorizers": {
      "href": "/restapis/wn611yeyp3/authorizers"
    },
    "restapi:delete": {
      "href": "/restapis/wn611yeyp3"
    },
    "restapi:deployments": {
      "href": "/restapis/wn611yeyp3/deployments{?limit}",
      "templated": true
    },
    "restapi:models": {
      "href": "/restapis/wn611yeyp3/models"
    },
    "restapi:resources": {
      "href": "/restapis/wn611yeyp3/resources{?limit,embed}",
      "templated": true
    },
    "restapi:stages": {
      "href": "/restapis/wn611yeyp3/stages{?deployment_id}",
      "templated": true
    },
    "restapi:update": {
      "href": "/restapis/wn611yeyp3"
    },
    "stage:by-name": {
      "href": "/restapis/wn611yeyp3/stages/{stage_name}",
      "templated": true
    },
    "stage:create": {
      "href": "/restapis/wn611yeyp3/stages"
    }
  },
  "createdDate": "2016-06-06T23:49:37Z",
  "id": "wn611yeyp3",
  "name": "HelloWorld"
}

Notice that the resulting merged API assumes the name of the API specified in the request payload, although it retains the original API identifier. Similarly, a new resource or method will replace the existing resource or method if the two share the same path. Any other new resources or methods are added to and any other existing resources or methods are retained in the updated API.

If you set mode=overwrite in the above request, the entire new API definition replaces the existing one, while the existing API identifier remains unchanged.

See Also

Import an API