Smithy CRUD API tips with open-api-gateway

[zetashift]

Heyho, thank you for this very cool PDK. I've been able to get started really quickly with it and Smithy provides a delightful experience. The video going through a PDK Smithy demo was also very helpful!

I do have some questions about some recommended ways to create a CRUD API using PDK and open-api-gateway.

• Say I have something like Foo and Bar resources, do I create a FooService and a BarService and each get their own lambda integration, or do I create one service Api and that service lists the Foo and Bar resources in their resources member?
• For CRUD operations like Get/Create, is it recommended creating 1 lambda per operation or do it all in a router?

[cogwirrel]

Hey! That's really awesome to hear, thank you! 😄

Say I have something like Foo and Bar resources, do I create a FooService and a BarService and each get their own lambda integration, or do I create one service Api and that service lists the Foo and Bar resources in their resources member?

I'd recommend the latter, a single service with a FooResource and a BarResource. Each SmithyApiGatewayXXXProject targets a single service and creates an API gateway API with all the operations/resources in the service. If you wanted to separate your Foo and Bar resources into completely separate API Gateway endpoints then you can create a FooService and a BarService but you'd need to create separate SmithyApiGatewayXXXProjects in your monorepo. I hope that makes sense! :)

For CRUD operations like Get/Create, is it recommended creating 1 lambda per operation or do it all in a router?

The choice of individual lambda vs router is completely up to you! There are a few advantages of each option that come to mind:

Router

• Users less likely to experience lambda cold start latency since all requests directed to same lambda
• Quicker/easier to define interceptors which apply to all operations in your api

Individual Lambdas

• Can scope lambda IAM role down to minimum actions for individual operations for better adherence to "principal of least privilege" (for the router your single lambda needs all permissions for all the operations)
• Separate cloudwatch log group for each operation rather than all api logs together which makes searching logs for an individual operation simpler (with a router I'd recommend structured logging so individual operations are searchable)

If it helps, recently I've been opting for the router as it's really nice for say an API that a website calls - no cold start means it's super responsive after your first few clicks :)

[zetashift]

Thank you! That is very clear information :D.

I have one more question, is there a way to try out the API I create with openapi-gateway locally without deploying the CDK constructs?

[cogwirrel]

No problem! 😄

Unfortunately right now there isn't an easy way to run it locally that I know of. Usually API Gateway APIs can be run locally using the AWS SAM CLI (see: serverless cdk testing and sam local start-api) but sadly it's not compatible with open-api-gateway at the moment 😞. open-api-gateway points the API Gateway API at an OpenAPI specification that's written to S3 by a custom resource at deploy time (which allows for your API to grow without too much impact to the cloudformation template size), but this means SAM can't find the definition while starting locally.

Please could you cut a feature request for this if you're interested? I can't guarantee when I'll next have bandwidth to investigate but I think it'd be a really useful feature! 😄

[zetashift]

Are there any examples of open-api-gateway and using the router?
I currently have a router.ts that exports a handlerRouter({ operationsHandlers }) but do I have to do anything else? Asking this because currently it just builds fine, but doesn't the Lambda integration need to know that the router exists? :P

[cogwirrel]

I haven't got a public example anywhere I don't think, but yes you're right the lambda integration needs to know the router exists :) So you might have router.ts like the readme example:

import { handlerRouter, sayHelloHandler, sayGoodbyeHandler } from "my-api-typescript-client";
import { corsInterceptor } from "./interceptors";
import { sayGoodbye } from "./handlers/say-goodbye";

const sayHello = sayHelloHandler(async ({ input }) => {
  return {
    statusCode: 200,
    body: {
      message: `Hello ${input.requestParameters.name}!`,
    },
  };
});

export const handler = handlerRouter({
  // Interceptors declared in this list will apply to all operations
  interceptors: [corsInterceptor],
  // Assign handlers to each operation here
  handlers: {
    sayHello,
    sayGoodbye,
  },
});

You then need to instantiate your API construct with integrations that point at a lambda function with router.ts as its handler. If you're using the router you can avoid repeating the integration every time you add a new operation by using the Operations.all helper method eg:

import { Operations } from 'my-api-typescript-client';
import { Authorizers, Integrations } from '@aws-prototyping-sdk/open-api-gateway';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { Construct } from 'constructs';
import { Api } from './api';

export class SampleApi extends Api {
  constructor(scope: Construct, id: string) {
    super(scope, id, {
      defaultAuthorizer: Authorizers.iam(),
      // Use the same integration for every operation.
      integrations: Operations.all({
        integration: Integrations.lambda(new NodejsFunction(scope, 'router', {
          entry: path.join(__dirname, 'router.ts'),
        })),
      }),
    });
  }
}

Hope that helps! :)

[zetashift]

That helped! Thank you very much. I got a successful build for my api, infra and frontend project.

However I'm in a world of hurt with ESM and CommonJS clashing, my lamba gives back:

{
    "errorType": "Runtime.HandlerNotFound",
    "errorMessage": "index.handler is undefined or not exported",
    "stack": [
        "Runtime.HandlerNotFound: index.handler is undefined or not exported",
        "    at Object.module.exports.load (/var/runtime/UserFunction.js:304:11)",
        "    at Object.<anonymous> (/var/runtime/index.js:43:34)",
        "    at Module._compile (internal/modules/cjs/loader.js:1085:14)",
        "    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)",
        "    at Module.load (internal/modules/cjs/loader.js:950:32)",
        "    at Function.Module._load (internal/modules/cjs/loader.js:790:12)",
        "    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12)",
        "    at internal/main/run_main_module.js:17:47"
    ]
}

[cogwirrel]

Nice! Ahhh ESM and CommonJS never seem to play nicely together :( The most success I've had when I have dependencies of both types is to use esbuild which seems to be able to bundle them both together nicely. The NodejsFunction construct uses esbuild under the hood so may help if you're not already using it? :)

[zetashift]

I had found the problem, it was that the generated lambda code does exports.router = ... instead of exports.handler so making sure the handler function was set correctly fixed it! And now to just write all the business logic :D