RFC: Allow customizations on AWS::Serverless::Function API event types

[beck3905]

Swagger seems to be an all-or-nothing approach to AWS::Serverless::Api resources. If the swagger definition is provided in the API then the entire API needs to defined in swagger. I often have a single AWS::Serverless::Function that needs some customization in how it should be defined in the API, but in order to accomplish that I would need to provide boilderplate swagger for the entire API plus my customization.

It would be much more convenient and simple if I could just add my customizations to the Lambda API event and the translator would apply these to the API definition for that specific function.

[keetonian]

@beck3905 I like this idea. Like you posted, there are several features in https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-method.html that could be useful in API Events.

Some of these issues are:

• Authorization Scopes (Authorizers: Support AuthorizationScopes #652)
• Request Models (Support APIGW Models in API Events #895)
• API Key Required (and usage plans) (Support API Gateway Logging Metrics, Usage Plans, EndpointConfiguration, and CORS #248)

Could you provide any sample syntax of how you might like to use some of these features? Or any other features that you think would be good to add to the API Event?

[beck3905]

@keetonian I recently had a use case where I had an API with caching enabled that requires an Authorization token. Because the caching only looks at the URL and not the headers the cache would return valid values for users with invalid tokens and would return data for other users. Obviously, this was a problem. I solved it by adding the Authorization header parameter to the Method Request and enabling caching on that parameter. Since Serverless::API is pretty much all or nothing with swagger, the only way to accomplish this was with swagger. However, if the https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-method.html#cfn-apigateway-method-requestparameters were available in the API event then I would've only had to add a small bit of configuration there to accomplish the same thing.

I suggest exposing the following properties in the API event source type:

• ApiKeyRequired
• AuthorizationScopes
• RequestModels (linked to Models defined in the Serverless::API resource)
• RequestParameters
• RequestValidatorId
• ResponseModels (mapping of status code to model and linked to Models defined in the Serverless::API resource)
• ResponseParameters (mapping of status code to parameters)

For example:

Resource:
  Api:
    Type: AWS::Serverless::Api
    Properties:
      Models: # use swagger format to define models. This gets passed through to the `definitions` section of swagger.
        User:   
          type: object
          required:
            - userName
          properties:
            userName:
              type: string
            firstName:
              type: string
            lastName:
              type: string
     ...

  Function:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            RestApiId: !Ref Api
            RequestModel: User    # reference by string name
            RequestParameters:
              - method.request.header.Authorization:
                   required: true
                   caching: true
            ResponseModels: 
              200: User  # reference by string name
            ResponseParameters:
              200:
                - method.response.header.Access-Control-Allow-Origin: "'*'"
            Auth:
              ApiKeyRequired: true
              Authorizer: MyCognitoAuthorizer
              OauthScopes:
                - scope3
            

[beck3905]

@keetonian I've submitted a PR for my first stab at this. I implemented the RequestModel support in #948. Would you please take a look?

[beck3905]

@keetonian I've just submitted a second PR for RequestParameters support in #953. Would you please also take a look at that?

[MohammedAlSafwanOld]

@keetonian is there an estimate date on when will this be released ?

[praneetap]

@MohammedAlSafwan We're working on making our release process more transparent to external customers, but we're not quite where we want to be yet. For now, you can see when we cut release branches, which can give you some indication of when we begin working on a specific release.

[praneetap]

@beck3905 While writing tests for this feature during our internal QA process for Release V1.15, here's what i discovered -

1. I found that setting method parameters to required didn't fail my request if it didn't have the query parameters. This is (i think) because api GW requires you to define request validators to make the required setting apply. What was your use case for adding the required flag?
2. I tried to test caching but it didn't work for me, until I set the Cache ttl on the Api GW console. On digging deeper we need to set MethodSettings on the API in the SAM template, or the settings on the method don't get applied, and the cache ttl value gets overwritten to 0. Here is the template that (finally) worked for me -

Globals:
  Api:
    OpenApiVersion: '3.0.1'
    CacheClusterEnabled: true
    CacheClusterSize: '0.5'
    MethodSettings:
      - ResourcePath: /one
        HttpMethod: "GET"
        CachingEnabled: true # required to enable caching
        CacheTtlInSeconds: 15 # optional
Resources:
  ApiParameterFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
        exports.handler = function(event, context, callback) {
            var returnVal = "undef";
            if (event.queryStringParameters.type === "time") {
                returnVal = "time " + Date.now();
            }

            if (event.queryStringParameters.type === "random") {
                returnVal = "Random " + Math.random();
            }

            callback(null, {
                "statusCode": 200,
                "body": returnVal
            });
        }
      Handler: index.handler
      Runtime: nodejs8.10
      Events:
        GetHtml:
          Type: Api
          Properties:
            Path: /one
            Method: get
            RequestParameters:
              - method.request.querystring.type:
                  Required: true
                  Caching: true
        AnotherGetHtml:
          Type: Api
          Properties:
            Path: /two
            Method: get

[beck3905]

@praneetap

1. Yes, I believe the behavior you described is the same when setting up required parameters in the API Gateway console. My use case for adding the required flag is for API Gateway to fail the request if the parameter is not present. Perhaps another property is need on the API event source object for RequestValidators.

2. I don't recall having to set the TTL or caching method settings. I just had to set the CacheClusterEnable: true and `CacheClusterSize' properties on the API. Maybe I missed the TTL when inspecting the result of the stack in the API Gateway console. Could this be handled by an update to documentation?

[praneetap]

@praneetap

1. Yes, I believe the behavior you described is the same when setting up required parameters in the API Gateway console. My use case for adding the required flag is for API Gateway to fail the request if the parameter is not present. Perhaps another property is need on the API event source object for RequestValidators.
2. I don't recall having to set the TTL or caching method settings. I just had to set the CacheClusterEnable: true and `CacheClusterSize' properties on the API. Maybe I missed the TTL when inspecting the result of the stack in the API Gateway console. Could this be handled by an update to documentation?

Thanks for getting back @beck3905

1. We will create a task and submit it for prioritization. Currently API GW will not fail if the parameter is not present, so the task would be to add x-amazon-apigateway-request-validators extension support in the swagger.

2. Doc update is absolutely necessary to the examples/ folder, but I also think having to specify MethodSettings for the api is awkward syntax. Ideally, setting caching on a parameter should do this for you. I am curious to hear your thoughts on it.