Amazon API Gateway REST API Reference

restapi:import

Creates an API from an external API definition.

HTTP Request

POST /restapis?mode=import{?failonwarnings}

Template Variable

Request Body

// raw byte array representing the api definition

Response

RestApi

Remarks

The maximum size of the API definition file is 2MB.

Depending on the operational context, you can append the following query string parameters to the request URL when calling the restapi:import link-relation:

  • To exclude DocumentationParts from the import, append the ignore=documentation query string to the request URL. This may be necessary if your API definition contains too many DocumentationPart entities.

  • To configure the endpoint type, append the endpointConfigurationTypes=EDGE orendpointConfigurationTypes=REGIONAL query string parameter to the request URL. The default endpoint type is EDGE.

  • To handle the imported basePath, append the basePath=ignore, basePath=prepend or basePath=split query string parameter to the request URL. For more information, see Handle Imported Swagger basePath.

Example: Import a Swagger API definition

Request

The following example request shows how to create an API in API Gateway using a Swagger API specification.

POST /restapis?mode=import&failonwarning=true&basePath=ignore HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160606T234936Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160606/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-06T23:48:44Z",
    "title": "my-sample-api"
  },
  "host": "fugvjdxtri.execute-api.us-east-1.amazonaws.com",
  "basePath": "/stage2",
  "schemes": [
    "https"
  ],
  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            },
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'application/xml'"
              },
              "responseTemplates": {
                "application/json": "$util.urlDecode(\"%3CkinesisStreams%3E#foreach($stream in $input.path('$.StreamNames'))%3Cstream%3E%3Cname%3E$stream%3C/name%3E%3C/stream%3E#end%3C/kinesisStreams%3E\")\n"
              }
            }
          },
          "requestTemplates": {
            "application/json": "{\n}"
          },
          "uri": "arn:aws:apigateway:us-east-1:kinesis:action/ListStreams",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "requestParameters": {
            "integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
          },
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object"
    }
  }
}
Response

The successful response returns a 200 OK and a RestApi resource representing the newly created API in API Gateway.

{
  "_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": "my-sample-api"
}

See Also

Import an API, AWS CLI