Serverless Framework v1.42.0 - API Gateway Logs, Binary Media Type Responses, Request Body Validations & More

It is now easier to build even more robust APIs using the Serverless Framework. The Serverless Framework v1.42.0 release adds support for REST API access logs and API Gateway binary media type responses. Furthermore it’s now possible to set API Gateway request body validations and API key values. In addition to that we also addressed bug fixes and enhancements. 3 bug fixes and 7 enhancements were merged and are now available in our v1.42.0 release.

API Gateway REST API logs

Operating a serverless REST service at scale requires access to logs in order to gain insights into the API usage and potential issues the current setup might run into.

With Serverless Framework v1.42.0 it’s easy to enable API access logs. Just set the corresponding value on the provider config level like so:

provider:
  logs:
    restApi: true

After a redeploy you should see a dedicated log group where all your services API requests will be logged.

Note that we’re planning to roll out some more fine grained configurability for API Gateway access logs. Feel free to join our discussion about potential enhancements in this issue.

Binary Media Type responses

Sometimes it’s a product requirement to not just support text-based REST APIs. What if a customer should be able to download .pdf invoices, .xlsx spreadsheets or you want to be able to return images based on API requests.

With Serverless Framework v1.42.0 it’s now possible to support a range of different Binary Media Types.

Enabling support for API Gateway binary responses is as easy as configuring the corresponding property on the provider level:

provider:
  apiGateway:
    binaryMediaTypes:
      - '*/*'

You could use the wildcard setup (as shown above) to allow all binary media types. Additionally you can specify which files you’ll return by using the following config:

provider:
  apiGateway:
    binaryMediaTypes:
      - 'image/png'
      - ‘image/jpeg’

Note that you might also want to make sure to return the correct Content-Type header and (e.g. base64) encoded body in your Lambda response.

Request body validation

Validations are useful to stop processing malformed requests early on. Having support for such checks on the API level is beneficial because it makes it possible to reject invalid requests at an early stage without the need to go all the way through until the request hits the Lamdba function which will reject it anyway.

Using the http event one can now configure request body validations which are JSON documents used by API Gateway to filter incoming API requests.

Setting request body validations is best done by creating a .json file with the definition of the validation. Currently, API Gateway only supports draft-04 compliant schemas. Here is an example:

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "The Root Schema",
  "required": [
    "username"
  ],
  "properties": {
    "username": {
      "type": "string",
      "title": "The Foo Schema",
      "default": "",
      "pattern": "^[a-zA-Z0-9]+$"
    }
  }
}

After that you just need to point to that file in your http request schema configuration:

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: users/create
          method: post
          request:
            schema:
              application/json: ${file(create_request.json)}

Note that you can also inline your JSON validation definition, however it’s often easier to just reference a file on your filesystem.

API Key values

Controlling access to your API Gateway is best done by leveraging usage plans and API Keys. The Serverless Framework already supports both via the apiKeys and usagePlan configs.

When using such configurations API Gateway took care of the API Key value generation.

The Serverless Framework v1.42.0 adds support to control such values, making it easier and more deterministic to generate and hand out API keys to users.

Here’s an example that shows how API keys and usage plans can be used with the new Serverless Framework version:

API key value definitions without usage plans

provider:
  apiKeys:
    - original # original format
    - name: new-key-and-value # name and value
      value: apikeyvalueapikeyvalue
    - name: only-name # only name
    - value: onlyvalueonlyvalueonlyvalue # only value
      description: description for the api key

API key value definitions with usage plans

provider:
  apiKeys:
    - free:
      - original # original format
      - name: new-key-and-value # name and value
        value: apikeyvalueapikeyvalue
      - name: only-name # only name
      - value: onlyvalueonlyvalueonlyvalue # only value
        description: Api key for ${self:provider.stage} stage
    - paid:
      - original-paid
  usagePlan:
    - free:
        quota:
          limit: 1
          offset: 2
          period: MONTH
        throttle:
          burstLimit: 100
          rateLimit: 200
    - paid:
        quota:
          limit: 1
          offset: 2
          period: MONTH
        throttle:
          burstLimit: 100
          rateLimit: 200

Bug Fixes

#5952 Support setting both proxy and ca file for awsprovider AWS config agent +20/-4 snurmine
#6040 Remove safeguards when using API Gateway Stage resource settings +2/-194 pmuens
#6042 Merging v1.41.1 changes back into master +12/-200 pmuens

Enhancements

#6026 Use region pseudo parameter +19/-7 daaru00
#6038 Add more specific sub command error handling +115/-0 TylerSustare
#6043 Support wildcard in API Gateway cors domains +23/-5 tdmartino
#6064 Allow Fn::Join in stream event arns +93/-33 Tybot204
#6070 Highlight skipping of deployments +72/-3 pmuens
#6079 Improve integration test of aws-scala-sbt +1/-1 NomadBlacky
#6084 SDK based API Gateway Stage updates +565/-73 pmuens

Documentation

#6027 Update cors.md +3/-3 fabiorogeriosj
#6052 Fix doc: How to update serverless +1/-1 maplain
#6061 Update event.md +1/-1 PatNeedham
#6068 Fix markup error with Authentication value +1/-1 rakeshyoga
#6075 Drop duplicate paragraph in aws/guide/credentials +0/-3 bfred-it
#6085 Update serverless.yml.md +2/-0 marcinhou
#6092 Fixed three small typos in doc +4/-4 0xflotus
#6093 fixed small errors in spotinst docs +6/-6 0xflotus

Features

#5956 AWS API Gateway request body validation +157/-1 dschep
#5982 Enable Setting Amazon API Gateway API Key Value +306/-465 laardee
#6000 Add authorization scopes support for cognito user pool integration +29/-8 herebebogans
#6057 Add support for API Gateway REST API Logs +309/-20 pmuens
#6063 Add support for API Gateway Binary Media Types +101/-63 pmuens
#6078 Implement logging with Log4j2 for aws-scala-sbt +38/-7 NomadBlacky