github.com/mweagle/Sparta@v1.15.0/docs_source/content/reference/apigateway/_index.md (about)

     1  ---
     2  date: 2016-03-09T19:56:50+01:00
     3  pre: "<b>API Gateway</b>"
     4  alwaysopen: false
     5  weight: 100
     6  ---
     7  
     8  # API Gateway
     9  
    10  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](https://aws.amazon.com/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.
    11  
    12  {{% children description="true"   %}}
    13  
    14  ## Concepts
    15  
    16  Before moving on to the examples, it's suggested you familiarize yourself with the API Gateway concepts.
    17  
    18  * [Gettting Started with Amazon API Gateway](http://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-intro.html)
    19  
    20  The API Gateway presents a powerful and complex domain model.  In brief, to integrate with the API Gateway, a service must:
    21  
    22    1. Define one or more AWS Lambda functions
    23    1. Create an API Gateway REST API instance
    24    1. Create one or more resources associated with the REST API
    25    1. Create one or more methods for each resource
    26    1. For each method:
    27        1. Define the method request params
    28        1. Define the integration request mapping
    29        1. Define the integration response mapping
    30        1. Define the method response mapping
    31    1. Create a stage for a REST API
    32    1. Deploy the given stage
    33  
    34  See a the [echo example](/reference/apigateway/echo_event) for a complete version.
    35  
    36  ## Request Types
    37  
    38  AWS Lambda supports multiple [function signatures](https://docs.aws.amazon.com/lambda/latest/dg/go-programming-model-handler-types.html). Some supported signatures include structured types, which are JSON un/marshalable structs that are automatically managed.
    39  
    40  To simplify handling API Gateway requests, Sparta exposes the [APIGatewayEnvelope](https://godoc.org/github.com/mweagle/Sparta/aws/events#APIGatewayEnvelope) type. This type provides an embeddable struct type whose fields and JSON serialization match up with the [Velocity Template](https://github.com/mweagle/Sparta/blob/master/resources/provision/apigateway/inputmapping_json.vtl) that's applied to the incoming API Gateway request.
    41  
    42  Embed the [APIGatewayEnvelope](https://godoc.org/github.com/mweagle/Sparta/aws/events#APIGatewayEnvelope) type in your own lambda's request type as in:
    43  
    44  ```go
    45  type FeedbackBody struct {
    46    Language string `json:"lang"`
    47    Comment  string `json:"comment"`
    48  }
    49  
    50  type FeedbackRequest struct {
    51    spartaEvents.APIGatewayEnvelope
    52    Body FeedbackBody `json:"body"`
    53  }
    54  ```
    55  
    56  Then accept your custom type in your lambda function as in:
    57  
    58  ```go
    59  func myLambdaFunction(ctx context.Context, apiGatewayRequest FeedbackRequest) (map[string]string, error) {
    60    language := apiGatewayRequest.Body.Language
    61    ...
    62  }
    63  ```
    64  
    65  ## Response Types
    66  
    67  The API Gateway [response mappings](https://docs.aws.amazon.com/apigateway/latest/developerguide/mappings.html) must make
    68  assumptions about the shape of the Lambda response. The default _application/json_ mapping template is:
    69  
    70  {{% import file="./static/source/resources/provision/apigateway/outputmapping_json.vtl" language="nohighlight" %}}
    71  
    72  This template assumes that your response type has the following JSON shape:
    73  
    74  ```json
    75  {
    76    "code" : int,
    77    "body" : {...},
    78    "headers": {...}
    79  }
    80  ```
    81  
    82  The [apigateway.NewResponse](https://godoc.org/github.com/mweagle/Sparta/aws/apigateway#NewResponse) constructor
    83  is a utility function to produce a canonical version of this response shape. Note that `header` keys must be lower-cased.
    84  
    85  To return a different structure change the content-specific mapping templates defined by the
    86  [IntegrationResponse](https://godoc.org/github.com/mweagle/Sparta#IntegrationResponse). See the
    87  [mapping template reference](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html) for more information.
    88  
    89  ## Custom HTTP Headers
    90  
    91  API Gateway supports returning custom HTTP headers whose values are extracted from your response. To return custom HTTP
    92  headers using the default VTL mappings, provide them as the optional third `map[string]string` argument to
    93  [NewResponse](https://godoc.org/github.com/mweagle/Sparta/aws/apigateway#NewResponse) as in:
    94  
    95  ```go
    96  func helloWorld(ctx context.Context,
    97    gatewayEvent spartaAWSEvents.APIGatewayRequest) (*spartaAPIGateway.Response, error) {
    98  
    99    logger, loggerOk := ctx.Value(sparta.ContextKeyLogger).(*logrus.Logger)
   100    if loggerOk {
   101      logger.Info("Hello world structured log message")
   102    }
   103  
   104    // Return a message, together with the incoming input...
   105    return spartaAPIGateway.NewResponse(http.StatusOK, &helloWorldResponse{
   106      Message: fmt.Sprintf("Hello world 🌏"),
   107      Request: gatewayEvent,
   108    },
   109      map[string]string{
   110        "X-Response": "Some-value",
   111      }), nil
   112  }
   113  ```
   114  
   115  ## Other Resources
   116  
   117  * [Walkthrough: API Gateway and Lambda Functions](http://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started.html)
   118  * [Use a Mapping Template to Override an API's Request and Response Parameters and Status Codes](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-override-request-response-parameters.html)