Amazon API Gateway REST API Reference

restapi:create

Creates a new API represented by a RestApi instance in API Gateway.

HTTP Request

POST /restapis

Request Body

{
  "name" : "String",
  "description" : "String",
  "version" : "String",
  "cloneFrom" : "String",
  "binaryMediaTypes" : [ "String" ],
  "minimumCompressionSize" : "Integer",
  "apiKeySource" : "String",
  "endpointConfiguration" : {
    "types" : [ "String" ]
  }
}

Request Body Fields

The request accepts the following fields in JSON format.

  • name
  • [Required] The name of the RestApi.

  • description
  • The description of the RestApi.

  • version
  • A version identifier for the API.

  • cloneFrom
  • The ID of the RestApi that you want to clone from.

  • binaryMediaTypes
  • The list of binary media types supported by the RestApi. By default, the RestApi supports only UTF-8-encoded text payloads.

  • minimumCompressionSize
  • A nullable integer that is used to enable compression (with non-negative between 0 and 10485760 (10M) bytes, inclusive) or disable compression (with a null value) on an API. When compression is enabled, compression or decompression is not applied on the payload if the payload size is smaller than this value. Setting it to zero allows compression for any payload size.

  • apiKeySource
  • The source of the API key for metering requests according to a usage plan. Valid values are:

    • HEADER to read the API key from the X-API-Key header of a request.
    • AUTHORIZER to read the API key from the UsageIdentifierKey from a custom authorizer.

  • endpointConfiguration
  • The endpoint configuration of this RestApi showing the endpoint types of the API.

    • types
    • A list of endpoint types of an API (RestApi) or its custom domain name (DomainName). For an edge-optimized API and its custom domain name, the endpoint type is "EDGE". For a regional API and its custom domain name, the endpoint type is REGIONAL.

Response

RestApi

Remarks

Example: Create a new API

Request

The following example request creates a blank API named "my-test-api".

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

{
    "name" : "my-test-api",
    "description" : "A sample API created programmatically by calling API Gateway control service using the REST API"
}
Response

The successful (201 Created) response returns the created API with a unique identifier ({"id" : "fugvjdxtri"}) in the payload. For brevity, the curies section is abbreviated.

{
  "_links": {
    "curies": [
       ...
    ],
    "self": {
      "href": "/restapis/fugvjdxtri"
    },
    "authorizer:by-id": {
      "href": "/restapis/fugvjdxtri/authorizers/{authorizer_id}",
      "templated": true
    },
    "authorizer:create": {
      "href": "/restapis/fugvjdxtri/authorizers"
    },
    "deployment:by-id": {
      "href": "/restapis/fugvjdxtri/deployments/{deployment_id}{?embed}",
      "templated": true
    },
    "deployment:create": {
      "href": "/restapis/fugvjdxtri/deployments"
    },
    "model:by-name": {
      "href": "/restapis/fugvjdxtri/models/{model_name}?flatten=false",
      "templated": true
    },
    "model:create": {
      "href": "/restapis/fugvjdxtri/models"
    },
    "resource:by-id": {
      "href": "/restapis/fugvjdxtri/resources/{resource_id}{?embed}",
      "templated": true
    },
    "resource:create": {
      "href": "/restapis/fugvjdxtri/resources/3kzxbg5sa2"
    },
    "restapi:authorizers": {
      "href": "/restapis/fugvjdxtri/authorizers"
    },
    "restapi:delete": {
      "href": "/restapis/fugvjdxtri"
    },
    "restapi:deployments": {
      "href": "/restapis/fugvjdxtri/deployments{?limit}",
      "templated": true
    },
    "restapi:models": {
      "href": "/restapis/fugvjdxtri/models"
    },
    "restapi:resources": {
      "href": "/restapis/fugvjdxtri/resources{?limit,embed}",
      "templated": true
    },
    "restapi:stages": {
      "href": "/restapis/fugvjdxtri/stages{?deployment_id}",
      "templated": true
    },
    "restapi:update": {
      "href": "/restapis/fugvjdxtri"
    },
    "stage:by-name": {
      "href": "/restapis/fugvjdxtri/stages/{stage_name}",
      "templated": true
    },
    "stage:create": {
      "href": "/restapis/fugvjdxtri/stages"
    }
  },
  "createdDate": "2016-06-01T18:53:41Z",
  "description": "A sample API created programmatically by calling API Gateway control service using the REST API",
  "id": "fugvjdxtri",
  "name": "my-test-api"
}

Example: Clone an API from an existing one

Request

The following example request creates an API named "my-test-cloned-api" using the cloneFrom option with an existing API identifier.

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

{
    "name" : "my-test-cloned-api",
    "description" : "A sample API cloned programmatically by calling API Gateway control service using the REST API",
    "cloneFrom" : "0n1anifwvf"
}
Response

The successful response returns a RestApi instance representing the newly cloned API. For brevity, the links section is abbreviated in the output

{
  "_links": {
     ...
  },
  "createdDate": "2016-06-01T19:10:57Z",
  "description": "A sample API cloned programmatically by calling API Gateway control service using the REST API",
  "id": "wklpc8beyl",
  "name": "my-test-cloned-api"
}

See Also

Creating an API, AWS CLI