Defining API Gateway Endpoints with SAM

We took a first look at defining API Gateway endpoints in the backgrounder lessons, and now with this tutorial we’re going to dive further into the details. We’ll focus on defining endpoints with the Serverless Application Model (SAM) here, and in the next tutorial we’ll do the same thing for OpenAPI.

Defining the API Resource

Let’s start by looking at the Admin API, which is the first resource defined in the admin.yaml template:

Apart from the MethodSettings and TracingEnabled elements, which we covered earlier in the CloudWatch section, there are only a few properties to expand on here. Line 61 constructs the stack-specific resource name; line 62 sets the stage name; the Auth element on lines 63-67 specifies the API keys security mechanism used for this API. Lastly, line 68 specifies one of the three deployment options for the API: EDGE, REGIONAL, or PRIVATE. The first option specifies that the API integrates with the AWS CloudFront service to proxy inbound calls from points of presence around the world. The last option specifies that network traffic to the API is restricted to private VPCs within AWS. The REGIONAL option that you see above specifies that the API is reachable in a single region over the public internet. (Note that “reachable” is not the same as having access permissions).

See the SAM API documentation for additional properties not used in the sample code: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html#sam-api-endpointconfiguration

Defining Lambdas & Event Mappings

Moving further down the admin.yaml template, in the code below we see the CreateDealer Lambda resource and its associated HTTP method and endpoint. This Lambda, as defined, will be triggered by HTTP POST calls to the Admin API on the “/admin/dealers” path that’s specified on line 87:

Now let’s look at the GetDealers Lambda, further down again in the admin.yaml template. Here you can see that the endpoint defines the “stateCode” query parameter on line 104:

Continuing down the admin.yaml template, here’s the GetDealer Lambda. Here you can see the “dealerId” path parameter for the endpoint, defined on line 119:

Using Proxy Integration

Switching back to the console, we can select the “/admin/dealers” path and the “POST” method for the CreateDealers Lambda that we saw defined above:

When we click through to the “Integration Request” page, we can see that the “Use Lambda Proxy Integration” property, on the centre-right, is set by default to true:

Having this property set to true means that requests, including all the headers, parameters, and body content, will be proxied through to the target Lambda without being transformed or filtered in any way.

When we go back to the previous console page and click the “Method Request” link, we can see the “Request Validator” property, on the right, is set to “NONE”:

With this property set to “NONE”, there is no API-level request validation. Combined with the proxy integration setting shown above, this means that incoming requests to the API, whatever they contain, are passed through to the Lambda that receives it. As we’ve noted, you won’t want to build APIs this way, without request validation, for third party applications. Instead, you’ll want to define APIs using OpenAPI, which we’ll cover next.