Smithy/OpenAPI Hello World Tutorial

[cogwirrel]

Introduction

The @aws-prototyping-sdk/type-safe-api package enables you to build an API using “model-driven development” – forcing you to start by thinking about how your customers will interact with your service, and to work backwards from there.

You can model your API operations, inputs and outputs using either Smithy or OpenAPI, and sit back as infrastructure, clients, documentation and lambda handler wrappers are generated for you – removing the heavy lifting and allowing you to focus on API design and the business logic behind your APIs.

Eliminate mistakes for both yourself and your customers by leveraging the power of type-safety, where generated client and server code ensures inputs and outputs conform to the Smithy or OpenAPI model.

The Goal

• Try out TypeSafeApiProject to get a feel for how to build APIs with Smithy or OpenAPI

Useful Links

• PDK Documentation
• Smithy Documentation
• OpenAPI Documentation
• Smithy Origin Story Video

Workshop

Prerequisites

• All the usual PDK prerequisites (node >=14, Java >= 8, etc)
• AWS credentials for your target account

Create a Monorepo

In the usual way, create a monorepo which will be the base for your project:

mkdir smithy-workshop
cd smithy-workshop
npx projen new --from @aws-prototyping-sdk/nx-monorepo

Add a Dependency on the Package

Update your .projenrc.ts to add a dependency on @aws-prototyping-sdk/type-safe-api:

import { NxMonorepoProject } from "@aws-prototyping-sdk/nx-monorepo";

const monorepo = new NxMonorepoProject({
  defaultReleaseBranch: "main",
  devDeps: [
    "@aws-prototyping-sdk/nx-monorepo",
    "@aws-prototyping-sdk/type-safe-api" // <- add this!
  ],
  name: "smithy-workshop",
});

monorepo.synth();

Then synthesize your project by running:

yarn projen

Synthesizing your project will generate the projects you have defined in your .projenrc.ts file. Changes to project structure and configuration are defined as code. For more details, take a look at the Projen Documentation.

Create the API Project

In your .projenrc.ts, create a new TypeSafeApiProject.

Select the model.language based on whether you’d like to define your model in Smithy or in OpenAPI (Smithy is recommended as it’s less verbose and has a really nice compiler), and pick the infrastructure.language that you’d like to write your CDK infrastructure in. We’ll use Smithy with TypeScript in this workshop. Pick runtime.languages for the languages you would like to write your API operations in. Note that you can mix and match languages to implement your operations.

Also add an AwsCdkTypescriptApp project for deploying your API quickly. Note that in your own application you'd likely opt for a CI/CD pipeline to manage your deployments (eg PDKPipelineTsProject) instead!

import { NxMonorepoProject } from "@aws-prototyping-sdk/nx-monorepo";
import { Language, ModelLanguage, TypeSafeApiProject } from "@aws-prototyping-sdk/type-safe-api";
import { AwsCdkTypeScriptApp } from "projen/lib/awscdk";

const monorepo = new NxMonorepoProject({
  defaultReleaseBranch: "main",
  devDeps: [
    "@aws-prototyping-sdk/nx-monorepo",
    "@aws-prototyping-sdk/type-safe-api",
  ],
  name: "smithy-workshop",
});

// Define the API
const api = new TypeSafeApiProject({
  parent: monorepo,
  outdir: "packages/api",
  name: "smithy-workshop-api",
  model: {
    language: ModelLanguage.SMITHY,
    options: {
      smithy: {
        serviceName: {
          namespace: "com.smithy",
          serviceName: "Workshop",
        },
      },
    },
  },
  // We select TypeScript as our infrastructure and runtime languages
  infrastructure: {
    language: Language.TYPESCRIPT,
  },
  runtime: {
    languages: [Language.TYPESCRIPT],
  },
});


new AwsCdkTypeScriptApp({
  cdkVersion: "2.0.0",
  defaultReleaseBranch: "main",
  name: "smithy-workshop-infra",
  parent: monorepo,
  outdir: "packages/infra",
  deps: [
    "@aws-prototyping-sdk/type-safe-api",
    api.runtime.typescript!.package.packageName,
    api.infrastructure.typescript!.package.packageName,
  ],
  tsconfig: {
    compilerOptions: {
      lib: ["dom", "es2019"],
    },
  },
});

monorepo.synth();

Synthesise:

yarn projen

Build

Our first build will generate code from the sample "hello world" API.

yarn build

Add the API to the CloudFormation Stack

In packages/infra, instantiate the generated Api construct to your stack in src/main.ts:

import { App, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Api } from "smithy-workshop-api-typescript-infra";
import { Authorizers, Integrations } from "@aws-prototyping-sdk/type-safe-api";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import * as path from "path";

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);

    new Api(this, "Api", {
      defaultAuthorizer: Authorizers.iam(),
      integrations: {
        sayHello: {
          integration: Integrations.lambda(new NodejsFunction(this, "SayHelloLambda", {
            entry: path.join(__dirname, "say-hello.ts"),
          })),
        },
      },
    });
  }
}

// for development, use account/region from cdk cli
const devEnv = {
  account: process.env.CDK_DEFAULT_ACCOUNT,
  region: process.env.CDK_DEFAULT_REGION,
};

const app = new App();

new MyStack(app, 'smithy-workshop-infra-dev', { env: devEnv });
// new MyStack(app, 'smithy-workshop-infra-prod', { env: prodEnv });

app.synth();

Implement the Lambda Handler

We pointed the sayHello operation at a lambda function in the file say-hello.ts. We need to implement that now!

Implement the lambda handler using the generated handler wrapper function, in packages/infra/src/say-hello.ts:

import { sayHelloHandler } from "smithy-workshop-api-typescript-runtime";

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

Now we can build and deploy:

yarn build
yarn nx run smithy-workshop-infra:deploy --require-approval never

Explore!

While your stack is deploying, take a look in the packages/api directory.

If you chose Smithy, you’ll have a model/src/main/smithy/main.smithy file which defines a hello world API - this is the file you can edit to add or change the operations exposed by your API. You can split your definition into multiple files in this directory.

If you chose OpenAPI, you’ll have a model/src/main/openapi/main.yaml file which defines a hello world API.

You'll also notice runtime and infrastructure directories - these projects are generated from your model so there's no need to edit them.

Call your API

When your API has deployed, try calling it! You can use awscurl as an easy way to call it from your CLI, or find it in the API Gateway console and use the “test” feature.

awscurl --service execute-api --region <your-aws-region> \
  https://your-api-gateway.your-aws-region.amazonaws.com/prod/hello?name=World

Add a new Operation

Update your Smithy / OpenAPI model to add a new operation! Note that whenever you update the model, you'll need to rebuild (yarn build) to regenerate code based on your updated API definition.

As a challenge, see if you can define the operation, implement it, and then call it!

[zetashift]

For the infra project, I'm running into the following error:

/Users/rishad/micx/node_modules/ts-node/src/index.ts:859
    return new TSError(diagnosticText, diagnosticCodes, diagnostics);
           ^
TSError: ⨯ Unable to compile TypeScript:
src/main.ts(6,11): error TS2345: Argument of type 'import("/Users/rishad/micx/packages/infra/node_modules/constructs/lib/construct").Construct' is not assignable to parameter of type 'import("/Users/rishad/micx/node_modules/constructs/lib/construct").Construct'.
  Types of property 'node' are incompatible.
    Type 'import("/Users/rishad/micx/packages/infra/node_modules/constructs/lib/construct").Node' is not assignable to type 'import("/Users/rishad/micx/node_modules/constructs/lib/construct").Node'.
      Types have separate declarations of a private property 'host'.
src/main.ts(20,13): error TS2345: Argument of type 'App' is not assignable to parameter of type 'Construct'.
  Types of property 'node' are incompatible.
    Type 'import("/Users/rishad/micx/node_modules/constructs/lib/construct").Node' is not assignable to type 'import("/Users/rishad/micx/packages/infra/node_modules/constructs/lib/construct").Node'.
      Types have separate declarations of a private property 'host'.
    at createTSError (/Users/rishad/micx/node_modules/ts-node/src/index.ts:859:12)
    at reportTSError (/Users/rishad/micx/node_modules/ts-node/src/index.ts:863:19)
    at getOutput (/Users/rishad/micx/node_modules/ts-node/src/index.ts:1077:36)
    at Object.compile (/Users/rishad/micx/node_modules/ts-node/src/index.ts:1433:41)
    at Module.m._compile (/Users/rishad/micx/node_modules/ts-node/src/index.ts:1617:30)
    at Module._extensions..js (node:internal/modules/cjs/loader:1308:10)
    at Object.require.extensions.<computed> [as .ts] (/Users/rishad/micx/node_modules/ts-node/src/index.ts:1621:12)
    at Module.load (node:internal/modules/cjs/loader:1117:32)
    at Function.Module._load (node:internal/modules/cjs/loader:958:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12) {
  diagnosticCodes: [ 2345, 2345 ]

I feel like I have some dependency problem, but I'm not sure how, my infra projen project is defined simply as:

new AwsCdkTypeScriptApp({
  cdkVersion: "2.0.0",
  defaultReleaseBranch: "main",
  name: "infra",
  parent: monorepo,
  outdir: "packages/infra",
  deps: [api.package.packageName],
});

Also the weird thing is that when I try to build the Hello World example here, I don't get this error. So I'm pretty sure it's on my end.

[zetashift]

Right to upgrade dependences it's a simple npx projen upgrade command away, that fixed it! :P