SAM Serverless implicit API vs AWS::Serverless::Api

Question

When configuring a SAM template and defining a AWS::Serverless::Function there is the Events param that accepts an Api type. Does this create an API Gateway resource? What is the difference between this event type and a standalone AWS::Serverless::Api resource?

Answer 1

The question asks about the APIs referred to in the Event source block of a SAM AWS::Serverless::Function type, such as:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyApi:
        Type: Api
        Properties:
          Path: /resource
          Method: GET

As mentioned in the docs in various places, these are called "implicit APIs" in SAM.

SAM creates resources of type AWS::Serverless::Api from the union of Api events defined on AWS::Serverless::Function resources - but only those that do not refer (via the RestApiId property) to AWS::Serverless::Api defined explicitly in the template.

Behind the scenes, SAM collects all of these implicit APIs, generates a Swagger, and creates the implicit APIs using this Swagger. This API defaults to a StageName called "Prod" which cannot be configured.

If you do need control over defining and documenting the API in Swagger, an AWS::Serverless::Api resource should be created explicitly. It would then be referred to this way:

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Events:
      MyApi:
        Type: Api
        Properties:
          Path: /resource
          Method: GET
          RestApiId: !Ref MyAPI  # Add this line

MyApi:
  Type: AWS::Serverless::Api
  Properties:
    StageName: Prod
    DefinitionBody:
      ...

So the only difference between them is how much control you have over their configuration, and the key consideration is whether or not you need to define either:

• StageName
• a Swagger definition (via DefinitionBody)

If you need control over either or both of these, then you need to define your API explicitly. Otherwise, you can probably use the implicit APIs.

Note also that AWS::Serverless::Api resources in SAM are "transformed" into CloudFormation resources of type AWS::ApiGateway::RestApi, AWS::ApiGateway::Stage, and AWS::ApiGateway::Deployment.

Note that this information is a summary of information found in these three source docs:

• https://github.com/awslabs/serverless-application-model/blob/develop/versions/2016-10-31.md#awsserverlessapi
• https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api
• https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst#implicit-apis

Answer 2

Taken from the documentation:

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.