Amazon API Gateway REST API Reference

RestApi

Represents a REST API.


Relation Description Method Templated
self

A relation that refers to the current resource.

 GET No
restapi:update

Changes properties of a RestApi resource.

 PATCH No
restapi:delete

Deletes the specified API.

 DELETE No
restapi:resources

Gets an API's resource collection as represented by a Resources instance.

This link relation offers the following templated variable(s):

  • limit: Optional.

    The maximum number of returned results per page. The default value is 25 and the maximum value is 500.

  • embed: Optional.

    A query parameter used to retrieve the specified resources embedded in the returned Resources resource in the response. This embed parameter value is a list of comma-separated strings. Currently, the request supports only retrieval of the embedded Method resources this way. The query parameter value must be a single-valued list and contain the "methods" string. For example, GET /restapis/{restapi_id}/resources?embed=methods.

 GET Yes
restapi:deployments

Gets an API's Deployments resource.

This link relation offers the following templated variable(s):

  • limit: Optional.

    The maximum number of returned results per page. The default value is 25 and the maximum value is 500.

 GET Yes
restapi:stages

Gets the collection of the Stage resources for a specified API.

This link relation offers the following templated variable(s):

  • deployment_id: Optional.

    The stages' deployment identifiers.

 GET Yes
restapi:models

Gets an API's model collection represented by a Models instance.

This link relation offers the following templated variable(s):

  • limit: Optional.

    The maximum number of returned results per page. The default value is 25 and the maximum value is 500.

 GET Yes
restapi:authorizers

Gets an API's collection of custom authorizers that is represented as an Authorizers instance.

This link relation offers the following templated variable(s):

  • limit: Optional.

    The maximum number of returned results per page. The default value is 25 and the maximum value is 500.

 GET Yes
restapi:request-validators

Gets the RequestValidators collection of a specified RestApi.

 GET No
restapi:documentation-parts

Gets the DocumentationParts collection of this API.

This link relation offers the following templated variable(s):

  • limit: Optional.

    The maximum number of returned results per page. The default value is 25 and the maximum value is 500.

  • type: Optional.

    The type of API entities of the to-be-retrieved documentation parts.

  • path: Optional.

    The path of API entities of the to-be-retrieved documentation parts.

 GET Yes
restapi:documentation-versions

Gets the DocumentationVersions collection of this API.

This link relation offers the following templated variable(s):

  • limit: Optional.

    The maximum number of returned results per page. The default value is 25 and the maximum value is 500.

 GET Yes
restapi:gateway-responses

Gets the GatewayResponses collection on this RestApi.

 GET No
resource:by-id

Gets an API resource of the Resource type for a given resource identifier.

This link relation offers the following templated variable(s):

  • resource_id: Required.

    [Required] The identifier for the Resource resource.

  • embed: Optional.

    A query parameter to retrieve the specified resources embedded in the returned Resource representation in the response. This embed parameter value is a list of comma-separated strings. Currently, the request supports only retrieval of the embedded Method resources this way. The query parameter value must be a single-valued list and contain the "methods" string. For example, GET /restapis/{restapi_id}/resources/{resource_id}?embed=methods.

 GET Yes
deployment:by-id

Gets a Deployment resource with the specified identifier.

This link relation offers the following templated variable(s):

  • deployment_id: Required.

    [Required] The identifier of the Deployment resource to get information about.

  • embed: Optional.

    A query parameter to retrieve the specified embedded resources of the returned Deployment resource in the response. In a REST API call, this embed parameter value is a list of comma-separated strings, as in GET /restapis/{restapi_id}/deployments/{deployment_id}?embed=var1,var2. The SDK and other platform-dependent libraries might use a different format for the list. Currently, this request supports only retrieval of the embedded API summary this way. Hence, the parameter value must be a single-valued list containing only the "apisummary" string. For example, GET /restapis/{restapi_id}/deployments/{deployment_id}?embed=apisummary.

 GET Yes
stage:by-name

Gets information about the Stage with the specified name.

This link relation offers the following templated variable(s):

  • stage_name: Required.

    [Required] The name of the Stage resource to get information about.

 GET Yes
model:by-name

Gets information about the Model of a specified name.

This link relation offers the following templated variable(s):

  • model_name: Required.

    [Required] The name of the model as an identifier.

  • flatten: Optional.

    A query parameter of a Boolean value to resolve (true) all external model references and returns a flattened model schema or not (false) The default is false.

 GET Yes
authorizer:by-id

Gets the Authorizer resource representing a custom authorizer of a specified identifier.

This link relation offers the following templated variable(s):

  • authorizer_id: Required.

    [Required] The identifier of the Authorizer resource.

 GET Yes
requestvalidator:by-id

Gets the RequestValidator of a given identifier for a specified API.

This link relation offers the following templated variable(s):

  • requestvalidator_id: Required.

    [Required] The identifier of the RequestValidator to be retrieved.

 GET Yes
documentationpart:by-id

Gets a DocumentationPart of a specified documentation part identifier.

This link relation offers the following templated variable(s):

  • part_id: Required.

    [Required] The string identifier of the associated RestApi.

 GET Yes
documentationversion:by-version

Gets a documentation snapshot of a specific version.

This link relation offers the following templated variable(s):

  • doc_version: Required.

    [Required] The version identifier of the to-be-retrieved documentation snapshot.

 GET Yes
gatewayresponse:by-type

Gets a GatewayResponse of a specified response type on the given RestApi.

This link relation offers the following templated variable(s):

  • response_type: Required.

    [Required]

    The response type of the associated GatewayResponse. Valid values are

    • ACCESS_DENIED
    • API_CONFIGURATION_ERROR
    • AUTHORIZER_FAILURE
    • AUTHORIZER_CONFIGURATION_ERROR
    • BAD_REQUEST_PARAMETERS
    • BAD_REQUEST_BODY
    • DEFAULT_4XX
    • DEFAULT_5XX
    • EXPIRED_TOKEN
    • INVALID_SIGNATURE
    • INTEGRATION_FAILURE
    • INTEGRATION_TIMEOUT
    • INVALID_API_KEY
    • MISSING_AUTHENTICATION_TOKEN
    • QUOTA_EXCEEDED
    • REQUEST_TOO_LARGE
    • RESOURCE_NOT_FOUND
    • THROTTLED
    • UNAUTHORIZED
    • UNSUPPORTED_MEDIA_TYPE

 GET Yes
resource:create

Creates an API resource.

 POST No
deployment:create

Creates a new Deployment for the API, which will be referenced by the provided Stage. If the specified stage already exists, it will be updated to point to the new deployment. If the stage does not exist, a new one will be created and point to this deployment.

POST No
stage:create

Creates a new Stage for this API.

 POST No
model:create

Creates a new Model for this API.

 POST No
authorizer:create

Creates an Authorizer resource.

 POST No
requestvalidator:create

Creates a RequestValidator for a specified RestApi.

 POST No
documentationpart:create

Creates a documentation part for a specified API target with the supplied content.

 POST No
documentationversion:create

Creates a documentation snapshot of an API.

 POST No
gatewayresponse:put

Creates a customization of a GatewayResponse of a specified response type and status code on the given RestApi.

This link relation offers the following templated variable(s):

  • response_type: Required.

    [Required]

    The response type of the associated GatewayResponse. Valid values are

    • ACCESS_DENIED
    • API_CONFIGURATION_ERROR
    • AUTHORIZER_FAILURE
    • AUTHORIZER_CONFIGURATION_ERROR
    • BAD_REQUEST_PARAMETERS
    • BAD_REQUEST_BODY
    • DEFAULT_4XX
    • DEFAULT_5XX
    • EXPIRED_TOKEN
    • INVALID_SIGNATURE
    • INTEGRATION_FAILURE
    • INTEGRATION_TIMEOUT
    • INVALID_API_KEY
    • MISSING_AUTHENTICATION_TOKEN
    • QUOTA_EXCEEDED
    • REQUEST_TOO_LARGE
    • RESOURCE_NOT_FOUND
    • THROTTLED
    • UNAUTHORIZED
    • UNSUPPORTED_MEDIA_TYPE

 PUT Yes
documentationpart:import

Imports documentation parts specified in an external (e.g., OpenAPI) definition file.

This link relation offers the following templated variable(s):

  • failonwarnings: Optional.

    A query parameter to specify whether to rollback the documentation importation (true) or not (false) when a warning is encountered. The default value is false.

  • mode: Optional.

    A query parameter to indicate whether to overwrite (OVERWRITE) any existing DocumentationParts definition or to merge (MERGE) the new definition into the existing one. The default value is MERGE.

 PUT Yes


Properties

{
  "id" : "String",
  "name" : "String",
  "description" : "String",
  "createdDate" : "Timestamp",
  "version" : "String",
  "warnings" : [ "String" ],
  "binaryMediaTypes" : [ "String" ],
  "minimumCompressionSize" : "Integer",
  "apiKeySource" : "String",
  "endpointConfiguration" : {
    "types" : [ "String" ],
    "vpcEndpointIds" : [ "String" ]
  },
  "policy" : "String",
  "tags" : {
    "String" : "String"
  },
  "disableExecuteApiEndpoint" : "Boolean"
}

  • id

  • The API's identifier. This identifier is unique across all of your APIs in API Gateway.

  • name

  • The API's name.

  • description

  • The API's description.

  • createdDate

  • The timestamp when the API was created.

  • version

  • A version identifier for the API.

  • warnings

  • The warning messages reported when failonwarnings is turned on during API import.

  • 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. For a private API, the endpoint type is PRIVATE.

  • vpcEndpointIds

  • A list of VpcEndpointIds of an API (RestApi) against which to create Route53 ALIASes. It is only supported for PRIVATE endpoint type.

  • policy

  • A stringified JSON policy document that applies to this RestApi regardless of the caller and Method configuration.

  • tags

  • The collection of tags. Each tag element is associated with a given resource.

  • disableExecuteApiEndpoint

  • Specifies whether clients can invoke your API by using the default execute-api endpoint. By default, clients can invoke your API with the default https://{api_id}.execute-api.{region}.amazonaws.com endpoint. To require that clients use a custom domain name to invoke your API, disable the default endpoint.

Remarks

See Also

Create an API