I think there are a few things to understand when working with API Gateway integration with Lambda.

Lambda Integration vs Lambda Proxy Integration

There used to be only Lambda Integration which requires mapping templates. I suppose this is why still seeing many examples using it.

• How to pass a querystring or route parameter to AWS Lambda from Amazon API Gateway

As of September 2017, you no longer have to configure mappings to access the request body.

• Serverless Architecture on AWS

Lambda Proxy Integration, If you enable it, API Gateway will map every request to JSON and pass it to Lambda as the event object. In the Lambda function you’ll be able to retrieve query string parameters, headers, stage variables, path parameters, request context, and the body from it.

Without enabling Lambda Proxy Integration, you’ll have to create a mapping template in the Integration Request section of API Gateway and decide how to map the HTTP request to JSON yourself. And you’d likely have to create an Integration Response mapping if you were to pass information back to the client.

Before Lambda Proxy Integration was added, users were forced to map requests and responses manually, which was a source of consternation, especially with more complex mappings.

Words need to navigate the thinking. To get the terminologies straight.

• Lambda Proxy Integration = Pass through
  Simply pass the HTTP request through to lambda.

• Lambda Integration = Template transformation
  Go through a transformation process using the Apache Velocity template and you need to write the template by yourself.

body is escaped string, not JSON

Using Lambda Proxy Integration, the body in the event of lambda is a string escaped with backslash, not a JSON.

"body": "{\"foo\":\"bar\"}" 

If tested in a JSON formatter.

Parse error on line 1:
{\"foo\":\"bar\"}
-^
Expecting 'STRING', '}', got 'undefined'

The document below is about response but it should apply to request.

• I received a "malformed Lambda proxy response" error or a 502 status code with Amazon API Gateway. How do I resolve this?

The body field, if you are returning JSON, must be converted to a string or it will cause further problems with the response. You can use JSON.stringify to handle this in Node.js functions; other runtimes will require different solutions, but the concept is the same.

For JavaScript to access it as a JSON object, need to convert it back into JSON object with json.parse in JapaScript, json.dumps in Python.

• How To Work with JSON in JavaScript

Strings are useful for transporting but you’ll want to be able to convert them back to a JSON object on the client and/or the server side.

The AWS documentation shows what to do.

if (event.body !== null && event.body !== undefined) {
    let body = JSON.parse(event.body)
    if (body.time) 
        time = body.time;
}
...
var response = {
    statusCode: responseCode,
    headers: {
        "x-custom-header" : "my custom header value"
    },
    body: JSON.stringify(responseBody)
};
console.log("response: " + JSON.stringify(response))
callback(null, response);

Building on insights from Matus, I now can better answer the rest of the questions from above:

• "What is an example of how to pass data "directly" on the event object in a Lambda function like in case #3?"

When setting up API Gateway with Lambda to send-through specific pieces of data you need to use a Mapping Template which gets setup in AWS API Gateway.

That mapping template itself is written in the Velocity Template Language (VTL) from the Apache Foundation. Ex for attaching only the "hello" data so it is accessible as const data = event.hello; // world, ex:

    { 
      "hello": $input.params('$hello')
    }

Note: VTL is very powerful, the above is not a realistic example of usage but smallest amount of VTL just to communicate the idea, see here and here for more detail

Jumping through the interface to set that Mapping Template is a bit of an ordeal for a starter example so here's illustrated steps:

Warning: Be sure to double-check what is actually displayed in the editor, since there might occasionally occur some funky/unexpected behavior on the Mapping Template when you change the dropdown. Sometimes you also reach unrecoverable issues involving the mapping template, it's best when starting out to go ahead and delete the method and restart from API Gateway.

• "For a simple Node script, case 2 appears to have the "overhead" of parsing event body from stringified JSON so that's an understandable downside, but why or when would Case 3 be a more desirable approach?

It all depends on how your Lambda is receiving its data.

The key insight from Matus is that this is all ultimately an implementation detail. Lambdas in this contrived example (ie set up a REST API via AWS Gateway, send a GET/POST to that API and have lambda do something with the data) can retrieve data 3 ways:

(1) URL parameters const data = event.queryStringParameters.hello; // world

(2) request body const data = event.body.hello; // world (see note below)

(3) directly on the event object const data = event.hello; // world

Note on 2: This requires selecting (a) Lambda Proxy Integration instead of using a mapping template and in your code you'll need JSON.parse the event body before accessing the data, see this answer for further details

All this depends on what it is being fed from API Gateway. In this specific example, I'm talking about doing a REST request to pass data on an API Gateway endpoint that then is processed by Lambda-- but lots of other services/triggers can send data to a Lambda script for analysis.

Other helpful resources:

• https://kennbrodhagen.net/2015/12/06/how-to-create-a-request-object-for-your-lambda-event-from-api-gateway/

• Getting json body in aws Lambda via API gateway

• Could not parse request body into json: Unexpected character (\'-\' (code 45)) AWS Lambda + API + Postman

• https://medium.com/@lakshmanLD/lambda-proxy-vs-lambda-integration-in-aws-api-gateway-3a9397af0e6d

• https://github.com/valgaze/documentdb-fun

Ex. a toy Lambda function echos back whatever is POST'd:

let client = null; // Data outside function handler (ex a DB connection or an incrementing value) can change within the handler code below and persist between Lamba invocations so long as the container is still "warm", see more for details: https://docs.aws.amazon.com/lambda/latest/dg/running-lambda-code.html

exports.handler = async (event, context) => {
    let data = {};

    // Lambda Proxy Integration
    if (event && event.body) {
        try {
            data = JSON.parse(event.body);
        } catch(e) { 
            return {
                statusCode: 400,
                body: JSON.stringify({message: 'There was an error parsing the JSON data posted to this endpoint', error:e})
            }
        }
    }

    try {

        // Echo back the data or perform transformations, pass on to another service, etc
        const response = {
            statusCode: 200,
            body: JSON.stringify({message: 'Data submitted', data})
        };

        return response;

    } catch(e) {
        // Report errors related with connection, auth, DB write, etc
        return {
          statusCode: 409,
          body: JSON.stringify({message: 'There was some type of catastrophic error', error:e})
      }
   }
};

Lambda itself has no awareness of or constraints¹ on what event will contain -- that is entirely at the discretion of the caller that invoked the Lambda function.

When AWS services invoke Lambda functions they often use a common standard format that includes everything in the array event.Records (which, in some cases, like S3 event notifications and Lambda@Edge triggers, will always contain exactly one member). Other use cases include an entirely different structure.

What to expect is determined by the service, so you'll want to review the documentation for the service that is invoking the lambda function. The service should be consistent, overall, though there may be attributes that appear or disappear depending in the specifics of the trigger.

Using AWS Lambda with Other Services in the AWS Lambda Developer Guide discusses this in more detail, and provides links to some service-specific documentation for some of the AWS services that interoperate with Lambda.

And, of course, a Lambda function doesn't necessarily need to be invoked by another AWS service at all -- you can invoke a Lambda function from your own code, or even from inside another Lambda function (even recursively), or from the Lambda console, and in these cases the payload would be whatever you send.

¹ no constraints is not strictly true, since the Lambda API expects the input payload to be JSON, but this isn't relevant in the sense being discussed, here. The Node.js runtime environment deserializes the JSON into event transparently before calling your handler. The "event object" (as it is commonly called) is indeed typically an object. Exactly where/how/whether this is constrained (as opposed to, say, event being an array or scalar -- which I have never encountered but seems possible) is also beyond the intended scope of my choice of the phrase "no constraints."

From the docs

When Lambda runs your function, it passes a context object to the handler. This object provides methods and properties that provide information about the invocation, function, and execution environment.

Event (and the args) are described here.

To put it more simply, think of event as an input to a regular function. Context is an extra input supplied by AWS to give you a variety of meta context and such.