Under the Hood of .NET-Based Lambda Function Parameters

This article assumes you have the relevant knowledge to set up and deploy a .NET-based lambda function. You can follow the instruction in this blog if you need some background. Now, let’s review some underlying features of this service so that you can produce more of it in the deployment phase and while it’s up in the air.

Before We Begin

Before diving into the deep water, to produce a benefit from this blog post, you should be familiar with Lambda function concepts and have AWS Explorer installed in your Visual Studio instance. Furthermore, you’d better obtain .NET Core version 2.1.3 or above.

If you haven’t experienced lambda function-based developing on C# .NET Core, you can follow my post and catch-up.

C# Lambda Handler Method Signature

Lambda function execution is trigger-based. The function receives JSON input and returns an output that is based on the invocation source type. The input includes relevant information about the source that triggered the function, whereas the output provides the necessary status of the execution. For example, the JSON input for S3 source includes relevant information about the bucket and the file that triggered the function and the operation (PUT, DELETE).

Input Parameters

A generic signature of the C# method for lambda service handlers includes two parameters: a  Stream object and an ILambdaContext interface:

public APIGatewayProxyResponse LambdaStreamHandler(Stream input, ILambdaContext context)
        {
            string inputString = string.Empty;
            context.Logger.LogLine("started 'LambdaStreamHandler' method");

            // Read the stream into a string
            if (input != null)
            {
                StreamReader streamReader = new StreamReader(input);
                inputString = streamReader.ReadToEnd();
            }

            context.Logger.LogLine($"LambdaStreamHandler: received the following string: {inputString}");

            // Create APIGateway response object that contains the input string.
            // For API Gateway trigger, any other response would generate an exception
            var response = new APIGatewayProxyResponse
            {
                StatusCode = (int)HttpStatusCode.OK,
                Body = inputString,
                Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
            };

            return response;
        }

Assuming the trigger is an API Gateway, the invocation of the URL ‘https://<URL>/<GW-name>/S3ServiceNet?param1=111&param2=222' will produce the following JSON input (I altered some fields to avoid disclosure of sensitive data), in which you can see the query parameters inside.

{  
   "resource":"/S3ServiceNet",
   "path":"/S3ServiceNet",
   "httpMethod":"GET",
   "headers":null,
   "multiValueHeaders":null,
   "queryStringParameters":{  
      "param2":"222",
      "param1":"111"
   },
   "multiValueQueryStringParameters":{  
      "param2":[  
         "222" ],
      "param1":[  
         "111" ]
   },
   "pathParameters":null,
   "stageVariables":null,
   "requestContext":{  
      "path":"/S3ServiceNet",
      "accountId":"9337048219888888888",
      "resourceId":"x6ya4u",
      "stage":"test-invoke-stage",
      "requestId":"60f456ad16-c003f-131e8-bd034-ab017b3b1faeb",
      "identity":{  
         "cognitoIdentityPoolId":null,
         "cognitoIdentityId":null,
         "apiKey":"test-invoke-api-key",
        .........
      },
      "resourcePath":"/S3ServiceNet",
      "httpMethod":"GET",
      "extendedRequestId":"XXXXXXXXXXXX=",
      "apiId":"XXXXAASSWWEE"
   },
   "body":null,
   "isBase64Encoded":false
}

C# Object Request Example

AWS provides C# objects that wrap the common triggers’ input, such as S3 and API Gateway, so instead of parsing the JSON input, you can easily interact with a C# object.

It can be demonstrated clearly by reviewing the APIGatewayProxyRequest object (under the Amazon.Lambda.APIGatewayEvents namespace), which represents the input of API Gateway. It holds a property named RequestContext (its namespace APIGatewayProxyRequest.ProxyRequestContext), which has a property named Identity.

If you find this hierarchy and the names familiar then you have a good short term memory, since this is the same JSON input given above.

Output Parameters

Similarly to the input, the response varies depending on the trigger’s type. AWS C#.NET Core libraries include tailored response objects based on the trigger.

For example, the expected response for an API Gateway call is the object APIGatewayProxyResponse, whereas the expected response for the S3 trigger is a simple String. If our method returns a different object type than expected, the invocation of the lambda function will fail and throw the following error:

Execution failed due to configuration error: Malformed Lambda proxy response

A valid C# method for handling an API Gateway trigger should receive the Stream or APIGatewayProxyRequest object and return APIGatewayProxyResponse:

APIGatewayProxyResponse LambdaHandler(APIGatewayProxyRequest input, ILambdaContext context)

You can find more about the AWS C# library in its GitHub project. Reviewing this code will shed more light about the objects’ structure and how to use this library (aws/aws-lambda-dotnet).

Serializing From a Stream to AWS C# Objects

The .NET library mentioned above also provides a JSON serializer class that facilitates the serialization and deserialization of lambda requests and response objects. The serialization logic is based on the open-source library Newtonsoft.Json.

Being able to deserialize the input stream gives you the flexibility to define a general handler signature that receives a stream and returns an object, while the specific logic can be based on the trigger’s input.

using Amazon.Lambda.APIGatewayEvents; // required for APIGatewayProxyRequest and APIGatewayProxyResponse objects
using Amazon.Lambda.Serialization.Json; // required for JsonSerializer object

// Define a class
....

// This method receives a stream and convefts it to APIGateway request object
public object LambdaStreamHandler(Stream input, ILambdaContext context)
{
     JsonSerializer jsonSerializer = new JsonSerializer();

     APIGatewayProxyRequest request = jsonSerializer.Deserialize<APIGatewayProxyRequest>(input);

     // place your logic here
     ......

     // Create APIGateway response object.
     // For API Gateway trigger, any other response would generate an exception
     var response = new APIGatewayProxyResponse
     {
         StatusCode = (int)HttpStatusCode.OK,
         Body = string.Empty,
         Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
     };

     return response;
}

You should note that deserialization of a mismatched object doesn’t throw any exception, therefore, it's a good idea to check the deserialized object’s properties before using them as part of your logic.

Manipulating Lambda Function's Input Parameters: The Incentives

In short, this post focuses on the entry point of an API Gateway resource, mainly on the incoming parameters’ route.

You might be wondering what the benefit of this intervention is. Why do I need to intercept in this mechanism? Well, I can think of a few reasons:

1. Filtering variables at the API Gateway level to avoid passing them to the lambda function.
2. Decoupling between the parameters that are sent to the API Gateway and the ones received by the lambda function; changing the name of a parameter or its format allows for the creation of a facade, which can differ from the calling service. The same applies to the response parameter.
3. Injecting additional parameters into the lambda function, such as stage variables or generic API Gateway variables.
4. Validating parameters before invoking the lambda function can prevent unnecessary calls, which alleviates the load and can reduce cost.
5. Ensuring the parameters format: converting a string to an integer or escaping a string.

Another Level Above: Accessing Input Parameters via API Gateway

After integrating the API Gateway with a lambda function, by default, the request is delivered as is. If you want to interfere and manipulate the input, you need to change the configuration of the Integration Request and uncheck the option “Use Lambda Proxy integration.”

After unchecking this checkbox, the option to alter the input parameters appears below. Look for the Mapping Templates area. This is the place you can manipulate the parameters that flow into the Lambda functions.

If you keep the mapping template empty, then no parameter will flow into the lambda function. Hence, it’s essential to fill it with valid mapping. Let’s see how to configure a simple mapping template, JSON based, that copies the query parameters and their values into the input for the lambda function.

{  
  "queryStringParameters": {
  #foreach($key in $input.params().querystring.keySet())#if($foreach.index > 0),#end
  "$key":"$input.params().querystring.get($key)"#end
  }
}

The above example is looping the query string parameters and build them into a valid JSON format. Eventually, it should look like that:

You can opt to manipulate the input and create another format or convention. This capability allows standardization of the Lambda function’s input, regardless of the parameters that end-clients sends.

Let’s look at another example. The script below takes the query string parameter named param and assigns it into a parameter called var1. By that, we can implement the renaming of parameters.

{
  "queryStringParameters": { "var1":"$input.params('param')" }
}
# Equivalent to using the explicit call to querystring:
{
  "queryStringParameters": { "var1":"$input.params().querystring.get('param')" }
}

Note that if you do not surround the input with quotation marks, then the input will be interpreted as a number. This feature can be useful as a validation to the input.

This intermediate decoupling step gives a level of flexibility in designing a lambda function and API Gateway. It also can be useful for ignoring parameters, renaming parameters, or omitting parameters and passing only on the relevant ones.

Note the Input String Format

In some cases, you need to keep the query string holder to queryStringParameters,since your lambda function expects this format. For example, if you’re working with the C# lambda objects ( APIGatewayProxyRequest), you need to keep the expected JSON format for a request. Otherwise, the C# object will not be parsed and built correctly.

However, if you choose to work with a native stream as the input for the lambda function, you can change the JSON structure as you wish since the stream will be parsed in the Lambda function, based on your desired structure. You can find more information about lambda function's input in the following article.

Wrapping Up

We covered the request part of the API Gateway. However, the response can be altered as well using the same concepts of a mapping template. It can be useful to alter and standardize the response format.

API Gateways are a useful tool to receive and handle incoming requests and divert them to the relevant destination. Besides controlling the request and response format and validation, other features can be useful to manage the load and the quality of service, such as caching and throttling. I encourage you to explore its additional capabilities to improve your usability of this service.

I hope you enjoyed this post. Thanks for reading and happy coding!

- Lior