API Gateway mapping templates

[garretcharp]

Is it currently possible to use this for api gateway mapping templates as well? If not support for this would be nice!

[sam-goodwin]

Yes, this is totally something we should do. We can make use of the existing TS->VTL code!

Let's define the requirements for a new construct, ApiIntegration:

1. type-safe representation of the API Gateway's velocity template environment

Taking a lesson from this feedback (#24), we should first implement a layer that is un-opinionated and 1:1 with the underlying input to an API Gateway Velocity Template.

This means defining static types for the $util, $input and $context global variables.

• $input - https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#input-variable-reference
• $context - https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference
• $util - https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#util-template-reference

The $input type depends on the Method's path, query params and body. How can the developer safely define types for $input?

Simplest idea is to define an interface with params, body and path. This maps 1:1 with the API Gateway configuration.

new ApiIntegration<{
  body: BodyType,
  params: ParamsType,
  path: PathType
}>(($input) => {
  $input
});

Perhaps we can do better by specifying the query params and path as a string, see https://twitter.com/mpocock1/status/1499002040168636420?s=20&t=j1cgOZeaFkevSnG4nOHl5A, but this may be going too far?

$util unfortunately collides with Appsync's $util object, so perhaps we should move them into namespaces:

appsync.$util
apigw.$util

2. API Gateway V1 integration

If you use the AWS CDK to generate APIs, developers create hierarchies of Resources and add Methods to them (i.e. GET, POST, PUT, etc.). See: https://docs.aws.amazon.com/cdk/api/v1/docs/aws-apigateway-readme.html

functionless's ApiIntegration can implement the Integration interface

const api = new apigateway.RestApi(this, "hello-api");
const person = api.root.addResource("people");

resource.addMethod("GET", new ApiIntegration($input => {
  // blah
}));

3. API Gateway V2 Integration

The API Gateway service has two versions, so we also need to support https://docs.aws.amazon.com/cdk/api/v1/docs/aws-apigatewayv2-readme.html

Can we do this without adding a second construct?

4. OpenAPI 3.0/Swagger Integration (for both API GW V1 and V2)

People developing professional APIs used as products often use OpenAPI or Swagger to define those APIs and then generate code. API Gateway allows developers to configure the API from the specification. Can we take advantage of this? Perhaps we can generate code for each of the Methods?

[sam-goodwin]

Another thing to note is that Appsync's dynamodb resolvers have a different interface than API gateway's. We will need to provide separate integration classes for Table.

Similar problem to step functions #7

[brendo-m]

I've been investigating this over the last few days, here are some notes I've kept.

Very roughly speaking, a request to an APIGW route is handled like this:

1. Authorize/rate limit, if auth/usage plan is configured
2. Validate request via a Request Method
3. Apply request mapping template, if one exists for the requests content type
4. Forward transformed response to the integration
5. Apply response mapping template, if one exists for the integration responses content type matching an optional regex on error/status code
6. Validate/map response with a Method Response before sending back to the client

Some relevant details:

• "Proxy integrations" are used when you don't want to transform your request/response. The whole request is sent to the integration, and the whole response is passed to the Method Response
• Integrations include mock integrations, HTTP integrations, Lambda integrations and AWS service integrations. Lambda integrations are a special case of AWS service integrations. HTTP and Lambda integrations can be proxies
• Passthrough behavior for request templates allows you to specify when to pass the request through as is to the integration. NEVER - never pass through, WHEN_NO_MATCH - when request content type doesn't match a template, WHEN_NO_TEMPLATES - only when there are no templates defined
• A Gateway Response is returned if a failure occurs before the integration. Simple mapping can be applied using only the $context VTL variable
• You configure a list of response mapping templates and each one must map to a Method Response in a 1:1 fashion. A regex is used to select which one to run. For Lambda integrations it applies to the error message, for HTTP integrations it applies to status code

A great and much more detailed write-up is here: https://www.alexdebrie.com/posts/api-gateway-elements.

This model has some implications for what we can and can't do with functionless.

• Strongly typing the request means we can easily generate a json schema and add it to the Method Request
• There can be multiple responses and the types should account for that. One idea is to return a union type where each component type has an associated status code. The tricky part will be figuring out the regex to use in the response mapping template.
• We could infer that when business logic involves no transformations an integration can be a proxy, but I think this might violate the principle of least surprise and be a footgun. Maybe we can provide 2 constructs, one which does transforms and one which does proxy integrations, with different APIs. There is still some benefit in generating schemas for validation even when using proxy integrations
• Content type being configurable complicates things. I think sticking to JSON for now will simplify matters

[brendo-m]

There are 2 approaches we could take to modelling the API:

Single function arg

This mirrors the current AppsyncResolver API

new ApiIntegration(
  (request: ApiRequest<{ pathParameters: { num: number } }>) => {
    const x = 1;
    const y = fn(request.pathParameters.num);
    return x + y.result;
  }
)

Here we define business logic in a single function and then convert this to the request/response templates and the integration with functionless. We'll use a MockIntegration if there are no service calls and fail if there are more than 1. Anything before the service call is request template, with the output being the argument to the call. Anything after is the response template. Error handling is tricky - how do we encode that the service call failing with a 500 should be mapped with a particular template? Maybe like this?

(request: ApiRequest<{ pathParameters: { num: number } }>) => {
  try {
    return httpCall(request.pathParameters.num) + 1; // response mapping template matching 200 status code
  } catch (err) {
    if (err.statusCode === '400') ...;  // response mapping template matching 400 status code
    if (err.statusCode === '500') ...;  // response mapping template matching 500 status code
  }
}

This seems tricky to enforce and hard to get right in the compiler.

Function args for each stage

Strongly type each stage of the request handling, very roughly like this:

type IntegrationFunction<I, O> = (input: I) => O;
class ApiIntegration<
  Request,
  IntegrationInput,
  IntegrationOutput,
  Response,
  Integration extends IntegrationFunction<IntegrationInput, IntegrationOutput>,
> {
  constructor(
    requestMapping: (req: Request) => IntegrationInput,
    integration: Integration,
    responseMapping: (res: IntegrationOutput) => Response
  ) {}
}

This is just a concept, in reality there is more nuance like optional mappings, type of integration to handle etc, and we'd ideally provide a fluent API mirroring the EventBus API, maybe like this:

new ApiIntegration<...>()
  .transformRequest(req => ...) // transform input
  .call(...) // call integration
  .handleSuccess(...) // 200 response mapping template
  .handleFailure("400", ...)  // 400 response mapping template
  .handleFailure("500", ...);  // 500 response mapping template

[sam-goodwin]

Strongly typing the request means we can easily generate a json schema and add it to the Method Request

We can generate a JSON schema describing the structure but not constraints such as min, max, etc. How will we support these?

1. Classes and decorators?

class GetItemRequest {
  constructor(
    @min(10)
    readonly limit: number;
  ) {}
}

2. Encode it at the type-level?

interface GetItemRequest {
  limit: Number<{ min: 10 }>;
}

3. Something like zod?

const GetItemRequest = {
  limit: number().min(10)
}

[brendo-m]

1 or 2 was what I was thinking of. Another possibility is to use comments similarly to how you can typecheck javascript code

class GetItemRequest {
  constructor(
    // @functionless(min = 5, max = 10)
    readonly limit: number;
  ) {}
}

Using zod is definitely an interesting idea. It's a joy to use for runtime typing, we wouldn't need that but the DSL is really nice. Maybe we could borrow the DSL and provide our own, compile time only type extensions so we don't leak any runtime code like validation logic into the bundles.

Definitely needs some more thorough investigation

[brendo-m]

Dived deep into the APIGW Mapping Templates today to see what we can support. There are some key differences to the Appsync VTL engine which make it much harder to use, but I think I have something workable.

Integrations modeled outside of templates

The obvious difference is that in AppSync you use the defined VTL helper functions to connect to data sources, for e.g. $util.dynamodb.toDynamoDB($context.arguments.id). In APIGW you don't have these helpers because you define Integrations directly on the Method, and the request and response templates come before and after respectively.

Not $context.stash

AppSync has a $context.stash variable where you can store variables for the life of the pipeline resolver - they will persist between different data source calls. APIGW doesn't have this, but it's easy to write a function that calls for one:

(request: ApiRequest<...>) => {
    const x = 1;
    const y = fn({ foo: "bar" });
    return x + y.result; // this line will be compiled to the responseTemplate, but we are referring to `x` which is defined in the requestTemplate
}

Luckily there is a workaround (cough hack) we can use - $context.requestOverride.path.stash can be used as a stash! See https://stackoverflow.com/questions/47918477/aws-api-gateway-use-mock-integration-to-echo-response-body/61482410#61482410. I've tested this fairly extensively and it works well.

No $util.toJson

Appsync provides this and it's core to how the existing code works. It uses VTL variables heavily to build the payloads/responses in memory and then calls $util.toJson to dump it out for the wire.

APIGW does not support this. It is, to be fair, a special case of VTL - it's not really a templating feature - and I imagine that they envisioned much simpler templates than we are trying to support. Alas, we need to replicate it. To do this, we need to solve two problems - determine types of variables, and handle recursively visiting nodes in an object or array.

To determine types of variables we can use the fact that variables in VTL are just Java objects and we can inspect their classes. For example a simple template #set($x = 1) $x.class.name will output java.lang.Integer. We can use this in #if directives to branch based on the type:

#set ( $string_class = 'java.lang.String' )
#set ( $int_class = 'java.lang.Integer' )
#set ( $double_class = 'java.lang.Double )
#set ( $bool_class = 'java.lang.Boolean' )
#set ( $map_class = 'java.util.LinkedHashMap' )
#set ( $list_class = 'java.util.ArrayList' )

...

#if ( $someVar.class.name == $string_class )
// handle string
#elseif ( $someVar.class.name == $int_class )
// handle int
// and so on
#end

This came from https://stackoverflow.com/questions/26378438/how-to-check-if-value-is-a-map-or-a-string-in-apache-velocity. Supposedly you can use isAssignableFrom but I was unable to get that to work.

Handling recursively walking an object is a harder challenge. VTL supports macros which looked promising, but unfortunately APIGW disables them.

Looking for an alternative led me to using #define like this. It's meant for simple substitutions, but we can abuse it to suit our needs.

The first thing to note is that it doesn't take an argument, and so it doesn't have local scope. This makes it unsuitable for recursion. To see why, consider this:

#define($test)
  #if($test_arg == "foo")
    #set($test_arg = "bar")
    $test
  #end
  $test_arg
#end

#set($test_arg = "foo")
$test

This prints

bar
bar

but we need to see

bar
foo

So we're going to have to manage local scope ourselves with a stack. Luckily this isn't too bad:

#set($stack = [])
#set($discard = $stack.add(0, 1)) ## push 1 to stack
#set($discard = $stack.add(0, 2)) ## push 2 to stack
$stack.get(0) ## print head
#set($discard = $stack.remove(0)) ## pop stack

We can fix the above if statement like so

#set($test_arg = "foo")

#set($stack = [])
#set($discard = $stack.add(0, $test_arg))
#define($test)
  #if($stack.get(0) == "foo")
    #set($discard = $stack.add(0, "bar"))
    $test
    #set($discard = $stack.remove(0))
  #end
  $stack.get(0)
#end

$test

which now prints out, as expected

bar
foo

Now we should be able to combine these two ideas into a working toJson "function" but API GW has one more nasty surprise in store: it only supports two levels of recursion using a define directive :(. This:

#set($ctr = 10)
#define($recurse)
  #if ($ctr > 0)
    $ctr
  #set($ctr = $ctr - 1)
    $recurse
  #end
#end

should count down from 10, but we actually see this:

10
9
$recurse

Super annoying, but they probably did this specifically to prevent infinite loops.

Last (hopefully) workaround we need is to break it down into multiple, differently named directives.

#set($total_ctr = 10)
#set($ctr = 0)

#define($recurse3)
  #if ($total_ctr > 0)
    $total_ctr
    #set($total_ctr = $total_ctr - 1)
    #set($ctr = $ctr + 1)
    #if($ctr == 2)
      #set($ctr = 0)
      HALT
    #else
      $recurse3
    #end
  #end
#end

#define($recurse2)
  #if ($total_ctr > 0)
    $total_ctr
    #set($total_ctr = $total_ctr - 1)
    #set($ctr = $ctr + 1)
    #if($ctr == 2)
      #set($ctr = 0)
      $recurse3
    #else
      $recurse2
    #end
  #end
#end

#define($recurse1)
  #if ($total_ctr > 0)
    $total_ctr
    #set($total_ctr = $total_ctr - 1)
    #set($ctr = $ctr + 1)
    #if($ctr == 2)
      #set($ctr = 0)
      $recurse2
    #else
      $recurse1
    #end
  #end
#end

$recurse1

Now we see more numbers:

10
9
8
7
6
5
HALT

[sam-goodwin]

Amazing work @brendo-m. I am completely surprised by the solution you have come up with, especially the recursion stack implementation.

Have you tested this with a big JSON payload? I'm wondering how it will impact the #foreach limit?

[brendo-m]

Using all this we can now define an absolute monstrosity of a VTL template that can serialize a variable to JSON:

#set ( $string_class = 'java.lang.String' )
#set ( $int_class = 'java.lang.Integer' )
#set ( $double_class = 'java.lang.Double' )
#set ( $bool_class = 'java.lang.Boolean' )
#set ( $map_class = 'java.util.LinkedHashMap' )
#set ( $list_class = 'java.util.ArrayList' )

#set($stack = [])
#set($discard = $stack.add(0, $obj))
#define($toJson)
  #if ( $string_class == $stack.get(0).class.name )
    "$stack.get(0)"
  #elseif ( $int_class == $stack.get(0).class.name )
    $stack.get(0)
  #elseif ( $double_class == $stack.get(0).class.name )
    $stack.get(0)
  #elseif ( $bool_class == $stack.get(0).class.name )
    $stack.get(0)
  #elseif ( $map_class == $stack.get(0).class.name )
  {
    #foreach( $i in ${stack.get(0).entrySet()} )
      #set($discard = $stack.add(0, $i.value))
      "$i.key": #if ($stack.size() <= 2) $toJson #else $toJson2 #end
      #if ( $foreach.hasNext ),#end
      #set($discard = $stack.remove(0))
    #end
  }
  #elseif ( $list_class == $stack.get(0).class.name )
  [
    #foreach( $i in ${stack.get(0)} )
      #set($discard = $stack.add(0, $i))
      #if ($stack.size() <= 2) $toJson #else $toJson2 #end
      #if ( $foreach.hasNext ),#end
      #set($discard = $stack.remove(0))
    #end
  ]
  #end
#end

#define($toJson2)
  #if ( $string_class == $stack.get(0).class.name )
    "$stack.get(0)"
  #elseif ( $int_class == $stack.get(0).class.name )
    $stack.get(0)
  #elseif ( $double_class == $stack.get(0).class.name )
    $stack.get(0)
  #elseif ( $bool_class == $stack.get(0).class.name )
    $stack.get(0)
  #elseif ( $map_class == $stack.get(0).class.name )
  {
    #foreach( $i in ${stack.get(0).entrySet()} )
      #set($discard = $stack.add(0, $i.value))
      "$i.key": #if ($stack.size() <= 2) $toJson #elseif ($stack.size() <= 4) $toJson2 #else toJson3 #end
      #if ( $foreach.hasNext ),#end
      #set($discard = $stack.remove(0))
    #end
  }
  #elseif ( $list_class == $stack.get(0).class.name )
  [
    #foreach( $i in ${stack.get(0)} )
      #set($discard = $stack.add(0, $i))
      #if ($stack.size() <= 2) $toJson #elseif ($stack.size() <= 4) $toJson2 #else toJson3 #end
      #if ( $foreach.hasNext ),#end
      #set($discard = $stack.remove(0))
    #end
  ]
  #end
#end

$toJson

This one will handle JSON objects of depth 3 or less. An example:

#set($obj = {})
#set($obj.D1_1 = "depth 1, item 1")
#set($obj.D1_2 = "depth 1, item 2")
#set($obj.D1_3 = "depth 1, item 3")
#set($obj.D1_4 = {})
#set($obj.D1_4.D2_1 = "depth 2, item 1")
#set($obj.D1_4.D2_2 = {})
#set($obj.D1_4.D2_2.D3_1 = "depth 3, item 1")
#set($obj.D1_5 = [])
#set($discard = $obj.D1_5.add("depth 1, item 1"))
#set($discard = $obj.D1_5.add(["depth 2, item 1", "depth 2, item 2"]))

...

#set($stack = [])
#set($discard = $stack.add(0, $obj))
$toJson

will output (very messily IRL):

{
  "D1_1": "depth 1, item 1",
  "D1_2": "depth 1, item 2",
  "D1_3": "depth 1, item 3",
  "D1_4": { "D2_1": "depth 2, item 1", "D2_2": { "D3_1": "depth 3, item 1" } },
  "D1_5": ["depth 1, item 1", ["depth 2, item 1", "depth 2, item 2"]]
}

We can support more deeply nested objects by adding more toJson<x> directives. We will just have to choose a reasonable depth to support and document it, and cause a VTL mapping failure if it's exceeded at runtime so we don't pass along incomplete payloads.

We'll also need to extensively test this given the number of workarounds/hacks it took to achieve.

Finally, my last thought on this matter:

[brendo-m]

Picking this back up after vacation. First thing to solve is figuring out how to handle typed query string/path params. They are all strings in the input map.

// VTL
PARAMS: $input.params()
NUM: $input.params('num')
#set($x = $input.params('num') + 1)
NUM + 1: $x

// URL: <host>/?num=123&xyz=true

// Result
PARAMS: {path={}, querystring={num=123, xyz=true}, header={}}
NUM: 123
NUM + 1: 1231

To confirm they are all strings:

// VTL
PARAMS: $input.params()
#foreach( $i in $input.params().querystring.entrySet() )
$i.key: $i.value.class
#end

// Result
PARAMS: {path={}, querystring={num=123, xyz=true}, header={}}
num: class java.lang.String
xyz: class java.lang.String

If a user types num as a number here then we want to see 124, not 123