One of the most powerful ways to use AWS Lambda is to make function publicly available over HTTPS. This is accomplished by connecting the AWS Lambda function with the API Gateway. In this section we’ll start with a simple “echo” example and move on to a lambda function that accepts user parameters and returns an expiring S3 URL.


Before moving on to the examples, it’s suggested you familiarize yourself with the API Gateway concepts.

The API Gateway presents a powerful and complex domain model. In brief, to integrate with the API Gateway, a service must:

  1. Define one or more AWS Lambda functions
  2. Create an API Gateway REST API instance
  3. Create one or more resources associated with the REST API
  4. Create one or more methods for each resource
  5. For each method:
    1. Define the method request params
    2. Define the integration request mapping
    3. Define the integration response mapping
    4. Define the method response mapping
  6. Create a stage for a REST API
  7. Deploy the given stage

See a the echo example for a complete version.

API Gateway Request Types

AWS Lambda supports multiple function signatures. Some supported signatures include structured types, which are JSON un/marshalable structs that are automatically managed.

To simplify handling API Gateway requests, Sparta exposes the APIGatewayEnvelope type. This type provides an embeddable struct type whose fields and JSON serialization match up with the Velocity Template that’s applied to the incoming API Gateway request.

To use the APIGatewayEnvelope type with your own custom request body, create a set of types as in:

type FeedbackBody struct {
	Language string `json:"lang"`
	Comment  string `json:"comment"`

type FeedbackRequest struct {
	Body FeedbackBody `json:"body"`

Then reference your custom type in your lambda function as in:

func myLambdaFunction(ctx context.Context, apiGatewayRequest FeedbackRequest) (map[string]string, error) {
  language := apiGatewayRequest.Body.Language

Custom HTTP Headers

API Gateway supports returning custom HTTP headers whose values are extracted from your response payload.

Assume your Sparta lambda function returns a JSON struct as in:

// API response struct
type helloWorldResponse struct {
  Location    string `json:"location"`
  Message     string `json:"message"`

To extract the location field and promote it to the HTTP Location header, you must configure the response data mappings:

// Promote the location key value to an HTTP header
  lambdaFn := sparta.HandleAWSLambda(
	apiGatewayResource, _ := api.NewResource("/hello", lambdaFn)

apiGWMethod, _ := apiGatewayResource.NewMethod("GET", http.StatusOK)
apiGWMethod.Responses[http.StatusOK].Parameters = map[string]bool{
  "method.response.header.Location": true,
apiGWMethod.Integration.Responses[http.StatusOK].Parameters["method.response.header.Location"] =

Note that as the helloWorldResponse structured type is serialized to the body property of the response, we include that path selector in the integration.response.body.location value.

See the related AWS Forum thread.

Other Resources