Skip to content

Latest commit

 

History

History
307 lines (253 loc) · 19.9 KB

sam-resource-api.md

File metadata and controls

307 lines (253 loc) · 19.9 KB
Raw

AWS::Serverless::Api

Creates a collection of Amazon API Gateway resources and methods that can be invoked through HTTPS endpoints.

An AWS::Serverless::Api resource need not be explicitly added to a AWS Serverless Application Definition template. A resource of this type is implicitly created from the union of Api events defined on AWS::Serverless::Function resources defined in the template that do not refer to an AWS::Serverless::Api resource.

An AWS::Serverless::Api resource should be used to define and document the API using OpenApi, which provides more ability to configure the underlying Amazon API Gateway resources.

Syntax

To declare this entity in your AWS SAM template, use the following syntax:

YAML

Type: AWS::Serverless::Api
Properties:
  [AccessLogSetting](#sam-api-accesslogsetting): [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
  [Auth](#sam-api-auth): [ApiAuth](sam-property-api-apiauth.md)
  [BinaryMediaTypes](#sam-api-binarymediatypes): List
  [CacheClusterEnabled](#sam-api-cacheclusterenabled): Boolean
  [CacheClusterSize](#sam-api-cacheclustersize): String
  [CanarySetting](#sam-api-canarysetting): [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
  [Cors](#sam-api-cors): String | [CorsConfiguration](sam-property-api-corsconfiguration.md)
  [DefinitionBody](#sam-api-definitionbody): String
  [DefinitionUri](#sam-api-definitionuri): String | [ApiDefinition](sam-property-api-apidefinition.md)
  [Domain](#sam-api-domain): [DomainConfiguration](sam-property-api-domainconfiguration.md)
  [EndpointConfiguration](#sam-api-endpointconfiguration): String
  [GatewayResponses](#sam-api-gatewayresponses): Map
  [MethodSettings](#sam-api-methodsettings): [MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings)
  [MinimumCompressionSize](#sam-api-minimumcompressionsize): Integer
  [Models](#sam-api-models): Map
  [Name](#sam-api-name): String
  [OpenApiVersion](#sam-api-openapiversion): String
  [StageName](#sam-api-stagename): String
  [Tags](#sam-api-tags): Map
  [TracingEnabled](#sam-api-tracingenabled): Boolean
  [Variables](#sam-api-variables): Map

Properties

AccessLogSetting Configures Access Log Setting for a stage.
Type: AccessLogSetting
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting) property of an AWS::ApiGateway::Stage.

Auth Configure authorization to control access to your API Gateway API.
For more information about configuring access using AWS SAM see Controlling Access to API Gateway APIs in the AWS Serverless Application Model Developer Guide.
Type: ApiAuth
Required: No
AWS CloudFormation Compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

BinaryMediaTypes List of MIME types that your API could return. Use this to enable binary support for APIs. Use ~1 instead of / in the mime types.
Type: List
Required: No
AWS CloudFormation Compatibility: This property is similar to the [BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes) property of an AWS::ApiGateway::RestApi. The list of BinaryMediaTypes is added to both the AWS CloudFormation resource and the OpenAPI document.

CacheClusterEnabled Indicates whether cache clustering is enabled for the stage.
Type: Boolean
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled) property of an AWS::ApiGateway::Stage.

CacheClusterSize The stage's cache cluster size.
Type: String
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize) property of an AWS::ApiGateway::Stage.

CanarySetting Configure a canary setting to a stage of a regular deployment.
Type: CanarySetting
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting) property of an AWS::ApiGateway::Stage.

Cors Manage Cross-origin resource sharing (CORS) for all your API Gateway APIs. Specify the domain to allow as a string or specify a dictionary with additional Cors configuration. NOTE: CORS requires AWS SAM to modify your OpenAPI definition. So, it works only if inline OpenApi is defined with DefinitionBody.
For more information about CORS, see Enable CORS for an API Gateway REST API Resource in the Amazon API Gateway Developer Guide..
NOTE: API Gateway requires literal values to be a quoted string, so you must include single quotes in the Allow___ values. For example, "'www.example.com'" is correct whereas "www.example.com" is not correct.
Type: String | CorsConfiguration
Required: No
AWS CloudFormation Compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

DefinitionBody OpenAPI specification that describes your API. If neither DefinitionUri nor DefinitionBody are specified, SAM will generate a DefinitionBody for you based on your template configuration.
Type: String
Required: No
AWS CloudFormation Compatibility: This property is similar to the [Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) property of an AWS::ApiGateway::RestApi. If certain properties are provided, content may be inserted or modified into the DefinitionBody before being passed to CloudFormation. Properties include Auth, BinaryMediaTypes, Cors, GatewayResponses, Models, and an EventSource of type Api on for a corresponding AWS::Serverless::Function.

DefinitionUri AWS S3 Uri, local file path, or location object of the the OpenAPI document defining the API. The AWS S3 object this property references must be a valid OpenAPI file. If neither DefinitionUri nor DefinitionBody are specified, SAM will generate a DefinitionBody for you based on your template configuration.
If a local file path is provided, the template must go through the workflow that includes the sam deploy or sam package command, in order for the definition to be transformed properly.
Intrinsic functions are not supported in external OpenApi files referenced by DefinitionUri. Use instead the DefinitionBody property with the Include Transform to import an OpenApi definition into the template.
Type: String | ApiDefinition
Required: No
AWS CloudFormation Compatibility: This property is similar to the [BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-bodys3location) property of an AWS::ApiGateway::RestApi. The nested Amazon S3 properties are named differently.

Domain Configures a custom domain for this API Gateway API.
Type: DomainConfiguration
Required: No
AWS CloudFormation Compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

EndpointConfiguration Specify the type of endpoint for API endpoint.
Valid values are REGIONAL, EDGE, or PRIVATE.
Type: String
Required: No
AWS CloudFormation Compatibility: This property is similar to the [EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration) property of an AWS::ApiGateway::RestApi. AWS SAM only accepts a single endpoint configuration string.

GatewayResponses Configures Gateway Reponses for an API. Gateway Responses are responses returned by API Gateway, either directly or through the use of Lambda Authorizers. For more information, see the documentation for the Api Gateway OpenApi extension for Gateway Responses.
Type: Map
Required: No
AWS CloudFormation Compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

MethodSettings Configures all settings for API stage including Logging, Metrics, CacheTTL, Throttling.
Type: MethodSettings
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings) property of an AWS::ApiGateway::Stage.

MinimumCompressionSize Allow compression of response bodies based on client's Accept-Encoding header. Compression is triggered when response body size is greater than or equal to your configured threshold. The maximum body size threshold is 10 MB (10,485,760 Bytes). - The following compression types are supported: gzip, deflate, and identity.
Type: Integer
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize) property of an AWS::ApiGateway::RestApi.

Models The schemas to be used by your API methods. These schemas can be described using JSON or YAML. See the Examples section at the bottom of this page for example models.
Type: Map
Required: No
AWS CloudFormation Compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

Name A name for the API Gateway RestApi resource
Type: String
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name) property of an AWS::ApiGateway::RestApi.

OpenApiVersion Version of OpenApi to use. This can either be 2.0 for the Swagger specification, or one of the OpenApi 3.0 versions, like 3.0.1. For more information about OpenAPI, see the OpenAPI Specification.
Note: Setting this property to any valid value will also remove the stage Stage that SAM creates.
Type: String
Required: No
AWS CloudFormation Compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

StageName The name of the stage, which API Gateway uses as the first path segment in the invoke Uniform Resource Identifier (URI).
Type: String
Required: Yes
AWS CloudFormation Compatibility: This property is similar to the [StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-stagename) property of an AWS::ApiGateway::Stage. It is required in SAM, but not required in API Gateway
Additional Notes: The Implicit API has a stage name of "Prod".

Tags A map (string to string) that specifies the tags to be added to this API Gateway stage. Keys and values are limited to alphanumeric characters. Keys can be 1 to 127 Unicode characters in length and cannot be prefixed with aws:. Values can be 1 to 255 Unicode characters in length.
Type: Map
Required: No
AWS CloudFormation Compatibility: This property is similar to the [Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tags) property of an AWS::ApiGateway::Stage. The Tags property in SAM consists of Key:Value pairs; in CloudFormation it consists of a list of Tag objects.

TracingEnabled Indicates whether active tracing with X-Ray is enabled for the stage.
Type: Boolean
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tracingenabled) property of an AWS::ApiGateway::Stage.

Variables A map (string to string) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: [A-Za-z0-9._~:/?#&=,-]+.
Type: Map
Required: No
AWS CloudFormation Compatibility: This property is passed directly to the [Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables) property of an AWS::ApiGateway::Stage.

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, it returns the ID of the underlying API Gateway API.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using Fn::GetAtt, see Fn::GetAtt.

RootResourceId The root resource ID for a RestApi resource, such as a0bc123d4e.

Examples

SimpleApiExample

A Hello World AWS SAM template file that contains a Lambda Function with an API endpoint. This is a full AWS SAM template file for a working serverless application.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
  ApiFunction: # Adds a GET api endpoint at "/" to the ApiGatewayApi via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.7
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

An AWS SAM template snippet with an API defined in an external Swagger file along with Lambda integrations and CORS configurations. This is just a portion of an AWS SAM template file showing an AWS::Serverless::Api definition. See GitHub for the full example.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      # Allows www.example.com to call these APIs
      # SAM will automatically add AllowMethods with a list of methods for this API
      Cors: "'www.example.com'"
      DefinitionBody: # Pull in an OpenApi definition from S3
        'Fn::Transform':
          Name: 'AWS::Include'
          # Replace "bucket" with your bucket name
          Parameters:
            Location: s3://bucket/swagger.yaml

ApiCognitoAuthExample

An AWS SAM template snippet with an API that uses AWS Cognito to authorize requests against the API. This is just a portion of an AWS SAM template file showing an AWS::Serverless::Api definition. See GitHub for the full example.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors: "'*'"
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn:
              Fn::GetAtt: [MyCognitoUserPool, Arn]

ApiModelsExample

An AWS SAM template snippet with an API that includes a Models schema. This is just a portion of an AWS SAM template file, showing an AWS::Serverless::Api definition with two model schemas.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Models:
        User:
          type: object
          required:
            - username
            - employee_id
          properties:
            username:
              type: string
            employee_id:
              type: integer
            department:
              type: string
        Item:
          type: object
          properties:
            count:
              type: integer
            category:
              type: string
            price:
              type: integer