DEPRECATED!

Please use the type-safe-api package instead. open-api-gateway will be removed in the GA 1.0 release.

type-safe-api offers several benefits over open-api-gateway:

• Code generation at build time:
  • You no longer need to run npx projen when you make changes to your API definition.
  • You no longer need to pollute your version control with generated code
• More intuitive directory structure
• Generated python projects use poetry, allowing for better local dependencies (eg no need to deploy a lambda layer for handlers to depend on the generated handler wrappers)

TypeSafeApi Migration Guide

Migration will vary a little depending on the language you are using, however the following rough steps can be used to migrate a project to use type-safe-api:

1. Create a TypeSafeApiProject in your .projenrc.ts, with a different outdir to your existing OpenApiGatewayXXXProject or SmithyApiGatewayXXXProject (which we assume is called api, ie const api = new SmithyApiGateway...). Make sure you select the appropriate modelLanguage based on whether your existing model is written in OpenApi or Smithy. We'll call it newApi (eg const newApi = new TypeSafeApiProject({...)
2. Duplicate any client dependencies in your .projenrc.ts so that packages depend on the equivalent package. (eg. if a package depends on api.generatedTypescriptClient, make sure it depends on newApi.typescriptClient).
3. Duplicate any infrastructure dependencies in your .projenrc.ts - the infrastructure is now a separate subproject rather than the top level API project. (eg if a package depended on api before, it should now depend on newApi.typescriptInfrastructure)
4. Synthesize with npx projen
5. Copy your model into the new directory:
   1. For Smithy, you can copy everything in <oldoutdir>/smithy/src/main/smithy directory into <newoutdir>/model/src/main/smithy
   2. For OpenAPI, copy your <oldoutdir>/src/spec.yaml to <newoutdir>/model/src/main/openapi, and rename it to main.yaml. Additionally, copy any other referenced OpenAPI files from <oldoutdir>/src/ into <newoutdir>/model/src/main/openapi if present.
6. Build your project using your build command (eg. yarn build in root of monorepo if using monorepo with yarn).
7. Update any imports for the Api construct to import from the new generated infrastructure project, eg. import { Api } from 'mynewapi-typescript-infra';
8. Update any imports for the generated clients to use the new generated client packages
9. Make sure any custom code / files / scripts added to the OpenApiGatewayXXXProject or SmithyApiGatewayXXXProject are moved to their appropriate new home, most likely your infrastructure project (eg AwsCdkTypeScriptApp).
10. Remove the OpenApiGatewayXXXProject or SmithyApiGatewayXXXProject from .projenrc.ts and run npx projen again
11. Delete the <oldoutdir>

OpenAPI Gateway

Define your APIs using Smithy or OpenAPI v3, and leverage the power of generated clients and documentation, automatic input validation, and type safe client and server code!

This package vends a projen project type which allows you to define an API using either Smithy or OpenAPI v3, and a construct which manages deploying this API in API Gateway, given an integration (eg a lambda) for every operation.

The project will generate models and clients from your api definition in your desired languages, and can be utilised both client side or server side in lambda handlers. The project type also generates a wrapper construct which adds type safety to ensure an integration is provided for every API operation.

When you change your API specification, just run npx projen again to regenerate all of this!

Project

Use the provided projen project types to get started with your API quickly! There are options for TypeScript, Python and Java:

• Smithy
  • SmithyApiGatewayTsProject
  • SmithyApiGatewayPythonProject
  • SmithyApiGatewayJavaProject
• OpenAPI
  • OpenApiGatewayTsProject
  • OpenApiGatewayPythonProject
  • OpenApiGatewayJavaProject

We recommend using the Smithy-based projects, given that Smithy has a less verbose and more powerful IDL (Interface Definition Language).

Choose the project type based on the language you'd like to write your CDK infrastructure in. Whichever option above you choose, you can still write your server-side code in any language.

It's recommended that these projects are used as part of an nx-monorepo project, as it makes setting up dependencies much easier, and you will not need to manage the build order of generated clients.

Typescript

OpenAPI

While it is recommended to use the project within an nx-monorepo, you can still use this as a standalone project if you like (eg npx projen new --from @aws-prototyping-sdk/open-api-gateway open-api-gateway-ts), however you will need to manage build order (ie building the generated client first, followed by the project).

For usage in a monorepo:

Create the project in your .projenrc:

1import { ClientLanguage, DocumentationFormat, OpenApiGatewayTsProject } from "@aws-prototyping-sdk/open-api-gateway";
2
3new OpenApiGatewayTsProject({
4  parent: myNxMonorepo,
5  defaultReleaseBranch: "mainline",
6  name: "my-api",
7  outdir: "packages/api",
8  clientLanguages: [ClientLanguage.TYPESCRIPT, ClientLanguage.PYTHON, ClientLanguage.JAVA],
9  documentationFormats: [DocumentationFormat.HTML2, DocumentationFormat.PLANTUML, DocumentationFormat.MARKDOWN],
10});

In the output directory (outdir), you'll find a few files to get you started.

|_ src/
    |_ spec/
        |_ spec.yaml - The OpenAPI specification - edit this to define your API
        |_ .parsed-spec.json - A json spec generated from your spec.yaml.
    |_ api/
        |_ api.ts - A CDK construct which defines the API Gateway resources to deploy your API. 
        |           This wraps the OpenApiGatewayRestApi construct and provides typed interfaces for integrations specific
        |           to your API. You shouldn't need to modify this, instead just extend it as in sample-api.ts.
        |_ sample-api.ts - Example usage of the construct defined in api.ts.
        |_ sample-api.say-hello.ts - An example lambda handler for the operation defined in spec.yaml, making use of the
                                     generated lambda handler wrappers for marshalling and type safety.
|_ generated/
    |_ typescript/ - A generated typescript API client.
    |_ python/ - A generated python API client.
    |_ java/ - A generated java API client.
    |_ documentation/
        |_ html2/ - Generated html documentation
        |_ markdown/ - Generated markdown documentation
        |_ plantuml/ - Generated plant uml documentation

If you would prefer to not generate the sample code, you can pass sampleCode: false to OpenApiGatewayTsProject.

To make changes to your api, simply update spec.yaml and run npx projen to synthesize all the typesafe client/server code!

The SampleApi construct uses NodejsFunction to declare the example lambda, but you are free to change this!

Smithy

To create a project with Smithy as your interface definition language (IDL), you can use the SmithyApiGatewayTsProject:

1import { ClientLanguage, DocumentationFormat, SmithyApiGatewayTsProject } from "@aws-prototyping-sdk/open-api-gateway";
2
3new SmithyApiGatewayTsProject({
4  parent: myNxMonorepo,
5  defaultReleaseBranch: "mainline",
6  name: "my-api",
7  outdir: "packages/api",
8  serviceName: {
9    namespace: "com.mycompany",
10    serviceName: "MyService",
11  },
12  clientLanguages: [ClientLanguage.TYPESCRIPT, ClientLanguage.PYTHON, ClientLanguage.JAVA],
13  documentationFormats: [DocumentationFormat.HTML2, DocumentationFormat.PLANTUML, DocumentationFormat.MARKDOWN],
14});

This will result in a directory structure similar to the following:

|_ smithy/
    |_ src/
        |_ main/
            |_ smithy - The Smithy model used to define your API. You can define as many .smithy files in here as you like.
    |_ build.gradle - Smithy build gradle file - use this to add dependencies/plugins used in your smithy build
    |_ settings.gradle - Setup for the Smithy gradle project
    |_ smithy-build.json - Smithy build configuration - managed via options on the projen project
|_ src/
    |_ spec/
        |_ .parsed-spec.json - A json spec generated from your Smithy model.
    |_ api/
        |_ api.ts - A CDK construct which defines the API Gateway resources to deploy your API. 
        |           This wraps the OpenApiGatewayRestApi construct and provides typed interfaces for integrations specific
        |           to your API. You shouldn't need to modify this, instead just extend it as in sample-api.ts.
        |_ sample-api.ts - Example usage of the construct defined in api.ts.
        |_ sample-api.say-hello.ts - An example lambda handler for the operation defined in spec.yaml, making use of the
                                     generated lambda handler wrappers for marshalling and type safety.
|_ generated/
    |_ typescript/ - A generated typescript API client.
    |_ python/ - A generated python API client.
    |_ java/ - A generated java API client.
    |_ documentation/
        |_ html2/ - Generated html documentation
        |_ markdown/ - Generated markdown documentation
        |_ plantuml/ - Generated plant uml documentation

Customisation

You can customise the Smithy project with several properties:

1new SmithyApiGatewayTsProject({
2  parent: myNxMonorepo,
3  defaultReleaseBranch: "mainline",
4  name: "my-api",
5  outdir: "packages/api",
6  clientLanguages: [],
7  // The fully qualified service name for your API
8  serviceName: {
9    namespace: "com.mycompany",
10    serviceName: "MyService",
11  },
12  // By default, the contents of `smithy-build/output` will be ignored by source control.
13  // Set this to false to include it, for example if you are generating clients directly from the smithy model.
14  ignoreSmithyBuildOutput: false,
15  // The gradle wrapper used for the smithy build is copied from the PDK itself if it does not already exist in
16  // the 'smithy' folder. By default, this gradle wrapper will be ignored by source control.
17  // Set this to false if you would like to check the gradle wrapper in to source control, for example if you want
18  // to use a different version of the gradle wrapper in your project.
19  ignoreGradleWrapper: false,
20  // Use smithyBuildOptions to control what is added to smithy-build.json. See more details below.
21  smithyBuildOptions: {
22    projections: {
23      "ts-client": {
24        "plugins": {
25          "typescript-codegen": {
26            "package" : "@my-test/smithy-generated-typescript-client",
27            "packageVersion": "0.0.1"
28          }
29        }
30      }
31    }
32  }
33});

smithyBuildOptions allows you to customise the Smithy build, used for generating clients from the Smithy model (eg above), or customising the OpenAPI generation.

OpenAPI generation can be customised by referencing the openapi projection as follows:

1smithyBuildOptions: {
2  projections: {
3    openapi: {
4      plugins: {
5        openapi: {
6          // Customise the openapi projection here...
7          forbidGreedyLabels: true,
8          ...
9        }
10      }
11    }
12  }
13}

The OpenAPI specification generated by this projection is used to create the CDK infrastructure, lambda handler wrappers, etc. Options for configuring OpenAPI generation can be found in the Smithy OpenAPI documentation.

Note that any additional dependencies required for projections/plugins can be added by modifying smithyBuildOptions, which in turn will add them to the smithy/build.gradle file:

1smithyBuildOptions: {
2  maven: {
3    dependencies: [
4      "software.amazon.smithy:smithy-validation-model:1.27.2",
5    ]
6  }
7}

Notice smithy-cli, smithy-model, smithy-openapi and smithy-aws-traits are always included in the build.gradle since they are required for converting your Smithy model to OpenAPI. You can customise the version of these dependencies by specifying them in smithyBuildOptions:

1smithyBuildOptions: {
2  maven: {
3    dependencies: [
4      "software.amazon.smithy:smithy-cli:1.27.0",
5      "software.amazon.smithy:smithy-model:1.27.0",
6      "software.amazon.smithy:smithy-openapi:1.27.0",
7      "software.amazon.smithy:smithy-aws-traits:1.27.0",
8    ]
9  }
10}

Python

OpenAPI

As well as typescript, you can choose to generate the cdk construct and sample handler in python.

1new OpenApiGatewayPythonProject({
2  parent: myNxMonorepo,
3  outdir: 'packages/myapi',
4  name: 'myapi',
5  moduleName: 'myapi',
6  version: '1.0.0',
7  authorName: 'jack',
8  authorEmail: 'me@example.com',
9  clientLanguages: [ClientLanguage.TYPESCRIPT, ClientLanguage.PYTHON, ClientLanguage.JAVA],
10});

You will need to set up a shared virtual environment and configure dependencies via the monorepo (see README.md for the nx-monorepo package). An example of a full .projenrc.ts might be:

1import { nx_monorepo } from "aws-prototyping-sdk";
2import { ClientLanguage, OpenApiGatewayPythonProject } from "@aws-prototyping-sdk/open-api-gateway";
3import { AwsCdkPythonApp } from "projen/lib/awscdk";
4
5const monorepo = new nx_monorepo.NxMonorepoProject({
6  defaultReleaseBranch: "main",
7  devDeps: ["aws-prototyping-sdk", "@aws-prototyping-sdk/open-api-gateway"],
8  name: "open-api-test",
9});
10
11const api = new OpenApiGatewayPythonProject({
12  parent: monorepo,
13  outdir: 'packages/myapi',
14  name: 'myapi',
15  moduleName: 'myapi',
16  version: '1.0.0',
17  authorName: 'jack',
18  authorEmail: 'me@example.com',
19  clientLanguages: [ClientLanguage.TYPESCRIPT],
20  venvOptions: {
21    // Use a shared virtual env dir.
22    // The generated python client will also use this virtual env dir
23    envdir: '../../.env',
24  },
25});
26
27// Install into virtual env so it's available for the cdk app
28api.tasks.tryFind('install')!.exec('pip install --editable .');
29
30const app = new AwsCdkPythonApp({
31  authorName: "jack",
32  authorEmail: "me@example.com",
33  cdkVersion: "2.1.0",
34  moduleName: "myapp",
35  name: "myapp",
36  version: "1.0.0",
37  parent: monorepo,
38  outdir: "packages/myapp",
39  deps: [api.moduleName],
40  venvOptions: {
41    envdir: '../../.env',
42  },
43});
44
45monorepo.addImplicitDependency(app, api);
46
47monorepo.synth();

You'll find the following directory structure in packages/myapi:

|_ myapi/
    |_ spec/
        |_ spec.yaml - The OpenAPI specification - edit this to define your API
        |_ .parsed-spec.json - A json spec generated from your spec.yaml.
    |_ api/
        |_ api.py - A CDK construct which defines the API Gateway resources to deploy your API. 
        |           This wraps the OpenApiGatewayRestApi construct and provides typed interfaces for integrations specific
        |           to your API. You shouldn't need to modify this, instead just extend it as in sample_api.py.
        |_ sample_api.py - Example usage of the construct defined in api.py.
        |_ handlers/
             |_ say_hello_handler_sample.py - An example lambda handler for the operation defined in spec.yaml, making use of the
                                              generated lambda handler wrappers for marshalling and type safety.
|_ generated/
    |_ typescript/ - A generated typescript API client.
    |_ python/ - A generated python API client.
    |_ java/ - A generated java API client.

For simplicity, the generated code deploys a lambda layer for the generated code and its dependencies. You may choose to define an entirely separate projen PythonProject for your lambda handlers should you wish to add more dependencies than just the generated code.

Smithy

Similar to typescript, you can use the SmithyApiGatewayPythonProject.

Java

OpenAPI

As well as TypeScript and Python, you can choose to generate the cdk construct and sample handler in Java.

1new OpenApiGatewayJavaProject({
2  parent: monorepo,
3  outdir: 'packages/myapi',
4  name: "myapi",
5  groupId: "com.mycompany",
6  artifactId: "my-api",
7  version: "1.0.0",
8  clientLanguages: [ClientLanguage.PYTHON, ClientLanguage.TYPESCRIPT],
9  documentationFormats: [DocumentationFormat.HTML2, DocumentationFormat.PLANTUML, DocumentationFormat.MARKDOWN],
10});

The output directory will look a little like this:

|_ src/
    |_ spec/
        |_ spec.yaml - The OpenAPI specification - edit this to define your API
    |_ main/
        |_ java/
            |_ api/
                |_ Api.java - A CDK construct which defines the API Gateway resources to deploy your API. 
                |             This wraps the OpenApiGatewayRestApi construct and provides typed interfaces for integrations specific
                |             to your API. You shouldn't need to modify this, instead just extend it as in SampleApi.java.
                |_ ApiProps.java - Defines properties for the CDK construct in Api.java
                |_ SampleApi.java - Example usage of the construct defined in Api.java
                |_ SayHelloHandler.java - An example lambda handler for the operation defined in spec.yaml, making use of the
                                        generated lambda handler wrappers for marshalling and type safety.
        |_ resources/
            |_ .parsed-spec.json - A json spec generated from your spec.yaml. This will be bundled in the project jar.
|_ generated/
    |_ typescript/ - A generated typescript API client
    |_ python/ - A generated python API client.
    |_ java/ - A generated java API client.
    |_ documentation/
        |_ html2/ - Generated html documentation
        |_ markdown/ - Generated markdown documentation
        |_ plantuml/ - Generated plant uml documentation

The SampleApi construct uses a lambda function which deploys the entire project jar as a simple way to get started with an api that deploys out of the box. This jar includes a lot of extra code and dependencies that you don't need in your lambda, so it's recommended that after experimenting with the construct, you separate your lambdas into another JavaProject. Please refer to the Java API Lambda Handlers section of this README for details on how to set this up.

Smithy

Similar to typescript and python, you can use the SmithyApiGatewayJavaProject.

Smithy IDL

Please refer to the Smithy documentation for how to write models in Smithy. A basic example is provided below:

1$version: "2"
2namespace example.hello
3
4use aws.protocols#restJson1
5
6@title("A Sample Hello World API")
7
8/// A sample smithy api
9@restJson1
10service Hello {
11    version: "1.0"
12    operations: [SayHello]
13}
14
15@readonly
16@http(method: "GET", uri: "/hello")
17operation SayHello {
18    input: SayHelloInput
19    output: SayHelloOutput
20    errors: [ApiError]
21}
22
23string Name
24string Message
25
26@input
27structure SayHelloInput {
28    @httpQuery("name")
29    @required
30    name: Name
31}
32
33@output
34structure SayHelloOutput {
35    @required
36    message: Message
37}
38
39@error("client")
40structure ApiError {
41    @required
42    errorMessage: Message
43}

Supported Protocols

Currently only AWS restJson1 is supported. Please ensure your service is annotated with the @restJson1 trait.

Multiple Files

You can split your definition into multiple files and folders, so long as they are all under the smithy/src/main/smithy directory in your API project.

Authorizers

Smithy supports adding API Gateway authorizers in the model itself. Given that at model definition time one usually does not know the ARN of the user pool or lambda function for an authorizer, it is recommended to add the authorizer(s) in your Api CDK construct.

If using Smithy generated clients, some authorizer traits (eg sigv4) will include configuring the client for that particular method of authorization, so it can be beneficial to still define authorizers in the model. We therefore support specifying authorizers in both the model and the construct, but note that the construct will take precedence where the authorizer ID is the same.

OpenAPI Specification

Your spec.yaml file defines your api using OpenAPI Version 3.0.3. An example spec might look like:

1openapi: 3.0.3
2info:
3  version: 1.0.0
4  title: Example API
5paths:
6  /hello:
7    get:
8      operationId: sayHello
9      parameters:
10        - in: query
11          name: name
12          schema:
13            type: string
14          required: true
15      responses:
16        '200':
17          description: Successful response
18          content:
19            'application/json':
20              schema:
21                $ref: '#/components/schemas/HelloResponse'
22components:
23  schemas:
24    HelloResponse:
25      type: object
26      properties:
27        message:
28          type: string
29      required:
30        - message

You can divide your specification into multiple files using $ref.

For example, you might choose to structure your spec as follows:

|_ spec/
    |_ spec.yaml
    |_ paths/
        |_ index.yaml
        |_ sayHello.yaml
    |_ schemas/
        |_ index.yaml
        |_ helloResponse.yaml

Where spec.yaml looks as follows:

1openapi: 3.0.3
2info:
3  version: 1.0.0
4  title: Example API
5paths:
6  $ref: './paths/index.yaml'
7components:
8  schemas:
9    $ref: './schemas/index.yaml'

paths/index.yaml:

1/hello:
2  get:
3    $ref: './sayHello.yaml'

paths/sayHello.yaml:

1operationId: sayHello
2parameters:
3 - in: query
4   name: name
5   schema:
6     type: string
7   required: true
8responses:
9  '200':
10    description: Successful response
11    content:
12      'application/json':
13        schema:
14          $ref: '../schemas/helloResponse.yaml'

schemas/index.yaml:

1HelloResponse:
2  $ref: './helloResponse.yaml'

schemas/helloResponse.yaml:

1type: object
2properties:
3  message:
4    type: string
5required:
6  - message

Construct

A sample construct is generated which provides a type-safe interface for creating an API Gateway API based on your OpenAPI specification. You'll get a type error if you forget to define an integration for an operation defined in your api.

1import { Authorizers, Integrations } from '@aws-prototyping-sdk/open-api-gateway';
2import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
3import { Construct } from 'constructs';
4import { Api } from './api';
5
6/**
7 * An example of how to wire lambda handler functions to the API
8 */
9export class SampleApi extends Api {
10  constructor(scope: Construct, id: string) {
11    super(scope, id, {
12      defaultAuthorizer: Authorizers.iam(),
13      integrations: {
14        // Every operation defined in your API must have an integration defined!
15        sayHello: {
16          integration: Integrations.lambda(new NodejsFunction(scope, 'say-hello')),
17        },
18      },
19    });
20  }
21}

Sharing Integrations

If you would like to use the same integration for every operation, you can use the Operations.all method from your generated client to save repeating yourself, for example:

1import { Operations } from 'my-api-typescript-client';
2import { Authorizers, Integrations } from '@aws-prototyping-sdk/open-api-gateway';
3import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
4import { Construct } from 'constructs';
5import { Api } from './api';
6
7export class SampleApi extends Api {
8  constructor(scope: Construct, id: string) {
9    super(scope, id, {
10      defaultAuthorizer: Authorizers.iam(),
11      // Use the same integration for every operation.
12      integrations: Operations.all({
13        integration: Integrations.lambda(new NodejsFunction(scope, 'say-hello')),
14      }),
15    });
16  }
17}

Authorizers

The Api construct allows you to define one or more authorizers for securing your API. An integration will use the defaultAuthorizer unless an authorizer is specified at the integration level. The following authorizers are supported:

• Authorizers.none - No auth
• Authorizers.iam - AWS IAM (Signature Version 4)
• Authorizers.cognito - Cognito user pool
• Authorizers.custom - A custom authorizer

Cognito Authorizer

To use the Cognito authorizer, one or more user pools must be provided. You can optionally specify the scopes to check if using an access token. You can use the withScopes method to use the same authorizer but verify different scopes for individual integrations, for example:

1export class SampleApi extends Api {
2  constructor(scope: Construct, id: string) {
3    const cognitoAuthorizer = Authorizers.cognito({
4      authorizerId: 'myCognitoAuthorizer',
5      userPools: [new UserPool(scope, 'UserPool')],
6    });
7
8    super(scope, id, {
9      defaultAuthorizer: cognitoAuthorizer,
10      integrations: {
11        // Everyone in the user pool can call this operation:
12        sayHello: {
13          integration: Integrations.lambda(new NodejsFunction(scope, 'say-hello')),
14        },
15        // Only users with the given scopes can call this operation
16        myRestrictedOperation: {
17          integration: Integrations.lambda(new NodejsFunction(scope, 'my-restricted-operation')),
18          authorizer: cognitoAuthorizer.withScopes('my-resource-server/my-scope'),
19        },
20      },
21    });
22  }
23}

For more information about scopes or identity and access tokens, please see the API Gateway documentation.

Custom Authorizer

Custom authorizers use lambda functions to handle authorizing requests. These can either be simple token-based authorizers, or more complex request-based authorizers. See the API Gateway documentation for more details.

An example token-based authorizer (default):

1Authorizers.custom({
2  authorizerId: 'myTokenAuthorizer',
3  function: new NodejsFunction(scope, 'authorizer'),
4});

An example request-based handler. By default the identitySource will be method.request.header.Authorization, however you can customise this as per the API Gateway documentation.

1Authorizers.custom({
2  authorizerId: 'myRequestAuthorizer',
3  type: CustomAuthorizerType.REQUEST,
4  identitySource: 'method.request.header.MyCustomHeader, method.request.querystring.myQueryString',
5  function: new NodejsFunction(scope, 'authorizer'),
6});

Integrations

Integrations are used by API Gateway to service requests.

Lambda Integration

Currently, the only built-in integration is a lambda integration. You can construct one using Integrations.lambda(yourLambdaFunction).

Custom Integrations

You can implement your own integrations by inheriting the Integration class and implementing its render method. This method is responsible for returning a snippet of OpenAPI which will be added as the x-amazon-apigateway-integration for an operation. Please refer to the API Gateway Swagger Extensions documentation for more details.

You can also optionally override the grant method if you need to use CDK to grant API Gateway access to invoke your integration.

Generated Client

Typescript

The typescript-fetch OpenAPI generator is used to generate OpenAPI clients for typescript. This requires an implementation of fetch to be passed to the client. In the browser one can pass the built in fetch, or in NodeJS you can use an implementation such as node-fetch.

Example usage of the client in a website:

1import { Configuration, DefaultApi } from "my-api-typescript-client";
2
3const client = new DefaultApi(new Configuration({
4  basePath: "https://xxxxxxxxxx.execute-api.ap-southeast-2.amazonaws.com",
5  fetchApi: window.fetch.bind(window),
6}));
7
8await client.sayHello({ name: "Jack" });

Python

The python OpenAPI generator is used to generate OpenAPI clients for python.

Example usage:

1from my_api_python import ApiClient, Configuration
2from my_api_python.api.default_api import DefaultApi
3
4configuration = Configuration(
5    host = "https://xxxxxxxxxx.execute-api.ap-southeast-2.amazonaws.com"
6)
7
8with ApiClient(configuration) as api_client:
9    client = DefaultApi(api_client)
10
11    client.say_hello(
12        query_params={
13            'name': "name_example",
14        },
15    )

You'll find details about how to use the python client in the README.md alongside your generated client.

Java

The java OpenAPI generator is used to generate OpenAPI clients for Java.

Example usage:

1import com.generated.api.myapijava.client.api.DefaultApi;
2import com.generated.api.myapijava.client.ApiClient;
3import com.generated.api.myapijava.client.Configuration;
4import com.generated.api.myapijava.client.models.HelloResponse;
5
6ApiClient client = Configuration.getDefaultApiClient();
7client.setBasePath("https://xxxxxxxxxx.execute-api.ap-southeast-2.amazonaws.com");
8
9DefaultApi api = new DefaultApi(client);
10HelloResponse response = api.sayHello("Adrian").execute()

You'll find more details about how to use the Java client in the README.md alongside your generated client.

Lambda Handler Wrappers

Lambda handler wrappers are also importable from the generated client. These provide input/output type safety, ensuring that your API handlers return outputs that correspond to your specification.

Typescript

1import { sayHelloHandler } from "my-api-typescript-client";
2
3export const handler = sayHelloHandler(async ({ input }) => {
4  return {
5    statusCode: 200,
6    body: {
7      message: `Hello ${input.requestParameters.name}!`,
8    },
9  };
10});

Handler Router

The lambda handler wrappers can be used in isolation as handler methods for separate lambdas. If you would like to use a single lambda function to serve all requests, you can do so with the handlerRouter.

1import { handlerRouter, sayHelloHandler, sayGoodbyeHandler } from "my-api-typescript-client";
2import { corsInterceptor } from "./interceptors";
3import { sayGoodbye } from "./handlers/say-goodbye";
4
5const sayHello = sayHelloHandler(async ({ input }) => {
6  return {
7    statusCode: 200,
8    body: {
9      message: `Hello ${input.requestParameters.name}!`,
10    },
11  };
12});
13
14export const handler = handlerRouter({
15  // Interceptors declared in this list will apply to all operations
16  interceptors: [corsInterceptor],
17  // Assign handlers to each operation here
18  handlers: {
19    sayHello,
20    sayGoodbye,
21  },
22});

Python

1from myapi_python.apis.tags.default_api_operation_config import say_hello_handler, SayHelloRequest, ApiResponse, SayHelloOperationResponses
2from myapi_python.model.api_error import ApiError
3from myapi_python.model.hello_response import HelloResponse
4
5@say_hello_handler
6def handler(input: SayHelloRequest, **kwargs) -> SayHelloOperationResponses:
7    return ApiResponse(
8        status_code=200,
9        body=HelloResponse(message="Hello {}!".format(input.request_parameters["name"])),
10        headers={}
11    )

Handler Router

The lambda handler wrappers can be used in isolation as handler methods for separate lambdas. If you would like to use a single lambda function to serve all requests, you can do so with the handler_router.

1from myapi_python.apis.tags.default_api_operation_config import say_hello_handler, SayHelloRequest, ApiResponse, SayHelloOperationResponses, handler_router, HandlerRouterHandlers
2from myapi_python.model.api_error import ApiError
3from myapi_python.model.hello_response import HelloResponse
4from other_handlers import say_goodbye
5from my_interceptors import cors_interceptor
6
7@say_hello_handler
8def say_hello(input: SayHelloRequest, **kwargs) -> SayHelloOperationResponses:
9    return ApiResponse(
10        status_code=200,
11        body=HelloResponse(message="Hello {}!".format(input.request_parameters["name"])),
12        headers={}
13    )
14
15handler = handler_router(
16  # Interceptors defined here will apply to all operations
17  interceptors=[cors_interceptor],
18  handlers=HandlerRouterHandlers(
19    say_hello=say_hello,
20    say_goodbye=say_goodbye
21  )
22)

Java

1import com.generated.api.myapijava.client.api.Handlers.SayHello;
2import com.generated.api.myapijava.client.api.Handlers.SayHello200Response;
3import com.generated.api.myapijava.client.api.Handlers.SayHelloRequestInput;
4import com.generated.api.myapijava.client.api.Handlers.SayHelloResponse;
5import com.generated.api.myapijava.client.model.HelloResponse;
6
7
8public class SayHelloHandler extends SayHello {
9    @Override
10    public SayHelloResponse handle(SayHelloRequestInput sayHelloRequestInput) {
11        return SayHello200Response.of(HelloResponse.builder()
12                .message(String.format("Hello %s", sayHelloRequestInput.getInput().getRequestParameters().getName()))
13                .build());
14    }
15}

Handler Router

The lambda handler wrappers can be used in isolation as handler methods for separate lambdas. If you would like to use a single lambda function to serve all requests, you can do so by extending the HandlerRouter class.

1import com.generated.api.myapijava.client.api.Handlers.SayGoodbye;
2import com.generated.api.myapijava.client.api.Handlers.HandlerRouter;
3import com.generated.api.myapijava.client.api.Handlers.Interceptors;
4import com.generated.api.myapijava.client.api.Handlers.SayHello;
5
6import java.util.Arrays;
7import java.util.List;
8
9// Interceptors defined here apply to all operations
10@Interceptors({ TimingInterceptor.class })
11public class ApiHandlerRouter extends HandlerRouter {
12    // You must implement a method to return a handler for every operation
13    @Override
14    public SayHello sayHello() {
15        return new SayHelloHandler();
16    }
17
18    @Override
19    public SayGoodbye sayGoodbye() {
20        return new SayGoodbyeHandler();
21    }
22}

Interceptors

The lambda handler wrappers allow you to pass in a chain of handler functions to handle the request. This allows you to implement middleware / interceptors for handling requests. Each handler function may choose whether or not to continue the handler chain by invoking chain.next.

Typescript

In typescript, interceptors are passed as separate arguments to the generated handler wrapper, in the order in which they should be executed. Call request.chain.next(request) from an interceptor to delegate to the rest of the chain to handle a request. Note that the last handler in the chain (ie the actual request handler which transforms the input to the output) should not call chain.next.

1import {
2  sayHelloHandler,
3  ChainedRequestInput,
4  OperationResponse,
5} from "my-api-typescript-client";
6
7// Interceptor to wrap invocations in a try/catch, returning a 500 error for any unhandled exceptions.
8const tryCatchInterceptor = async <RequestParameters, RequestArrayParameters, RequestBody, Response>(
9  request: ChainedRequestInput<RequestParameters, RequestArrayParameters, RequestBody, Response>
10): Promise<Response | OperationResponse<500, { errorMessage: string }>> => {
11  try {
12    return await request.chain.next(request);
13  } catch (e: any) {
14    return { statusCode: 500, body: { errorMessage: e.message }};
15  }
16};
17
18// tryCatchInterceptor is passed first, so it runs first and calls the second argument function (the request handler) via chain.next
19export const handler = sayHelloHandler(tryCatchInterceptor, async ({ input }) => {
20  return {
21    statusCode: 200,
22    body: {
23      message: `Hello ${input.requestParameters.name}!`,
24    },
25  };
26});

Another example interceptor might be to record request time metrics. The example below includes the full generic type signature for an interceptor:

1import {
2  ChainedRequestInput,
3} from 'my-api-typescript-client';
4
5const timingInterceptor = async <RequestParameters, RequestArrayParameters, RequestBody, Response>(
6  request: ChainedRequestInput<RequestParameters, RequestArrayParameters, RequestBody, Response>
7): Promise<Response> => {
8  const start = Date.now();
9  const response = await request.chain.next(request);
10  const end = Date.now();
11  console.log(`Took ${end - start} ms`);
12  return response;
13};

Interceptors may mutate the interceptorContext to pass state to further interceptors or the final lambda handler, for example an identityInterceptor might want to extract the authenticated user from the request so that it is available in handlers.

1import {
2  LambdaRequestParameters,
3  LambdaHandlerChain,
4} from 'my-api-typescript-client';
5
6const identityInterceptor = async <RequestParameters, RequestArrayParameters, RequestBody, Response>(
7  request: ChainedRequestInput<RequestParameters, RequestArrayParameters, RequestBody, Response>
8): Promise<Response> => {
9  const authenticatedUser = await getAuthenticatedUser(request.event);
10  return await request.chain.next({
11    ...request,
12    interceptorContext: {
13      ...request.interceptorContext,
14      authenticatedUser,
15    },
16  });
17};

Python

In Python, a list of interceptors can be passed as a keyword argument to the generated lambda handler decorator, for example:

1from myapi_python.apis.tags.default_api_operation_config import say_hello_handler, SayHelloRequest, ApiResponse, SayHelloOperationResponses
2from myapi_python.model.api_error import ApiError
3from myapi_python.model.hello_response import HelloResponse
4
5@say_hello_handler(interceptors=[timing_interceptor, try_catch_interceptor])
6def handler(input: SayHelloRequest, **kwargs) -> SayHelloOperationResponses:
7    return ApiResponse(
8        status_code=200,
9        body=HelloResponse(message="Hello {}!".format(input.request_parameters["name"])),
10        headers={}
11    )

Writing an interceptor is just like writing a lambda handler. Call chain.next(input) from an interceptor to delegate to the rest of the chain to handle a request.

1import time
2from myapi_python.apis.tags.default_api_operation_config import ChainedApiRequest, ApiResponse
3
4def timing_interceptor(input: ChainedApiRequest) -> ApiResponse:
5    start = int(round(time.time() * 1000))
6    response = input.chain.next(input)
7    end = int(round(time.time() * 1000))
8    print("Took {} ms".format(end - start))
9    return response

Interceptors may choose to return different responses, for example to return a 500 response for any unhandled exceptions:

1import time
2from myapi_python.model.api_error import ApiError
3from myapi_python.apis.tags.default_api_operation_config import ChainedApiRequest, ApiResponse
4
5def try_catch_interceptor(input: ChainedApiRequest) -> ApiResponse:
6    try:
7        return input.chain.next(input)
8    except Exception as e:
9        return ApiResponse(
10            status_code=500,
11            body=ApiError(errorMessage=str(e)),
12            headers={}
13        )

Interceptors are permitted to mutate the "interceptor context", which is a Dict[str, Any]. Each interceptor in the chain, and the final handler, can access this context:

1def identity_interceptor(input: ChainedApiRequest) -> ApiResponse:
2    input.interceptor_context["AuthenticatedUser"] = get_authenticated_user(input.event)
3    return input.chain.next(input)

Interceptors can also mutate the response returned by the handler chain. An example use case might be adding cross-origin resource sharing headers:

1def add_cors_headers_interceptor(input: ChainedApiRequest) -> ApiResponse:
2    response = input.chain.next(input)
3    return ApiResponse(
4        status_code=response.status_code,
5        body=response.body,
6        headers={
7            **response.headers,
8            "Access-Control-Allow-Origin": "*",
9            "Access-Control-Allow-Headers": "*"
10        }
11    )

Java

In Java, interceptors can be added to a handler via the @Interceptors class annotation:

1import com.generated.api.myjavaapi.client.api.Handlers.Interceptors;
2
3@Interceptors({ TimingInterceptor.class, TryCatchInterceptor.class })
4public class SayHelloHandler extends SayHello {
5    @Override
6    public SayHelloResponse handle(SayHelloRequestInput sayHelloRequestInput) {
7        return SayHello200Response.of(HelloResponse.builder()
8                .message(String.format("Hello %s", sayHelloRequestInput.getInput().getRequestParameters().getName()))
9                .build());
10    }
11}

To write an interceptor, you can implement the Interceptor interface. For example, a timing interceptor:

1import com.generated.api.myjavaapi.client.api.Handlers.Interceptor;
2import com.generated.api.myjavaapi.client.api.Handlers.ChainedRequestInput;
3import com.generated.api.myjavaapi.client.api.Handlers.Response;
4
5public class TimingInterceptor<Input> implements Interceptor<Input> {
6    @Override
7    public Response handle(ChainedRequestInput<Input> input) {
8        long start = System.currentTimeMillis();
9        Response res = input.getChain().next(input);
10        long end = System.currentTimeMillis();
11        System.out.printf("Took %d ms%n", end - start);
12        return res;
13    }
14}

Interceptors may choose to return different responses, for example to return a 500 response for any unhandled exceptions:

1import com.generated.api.myjavaapi.client.api.Handlers.Interceptor;
2import com.generated.api.myjavaapi.client.api.Handlers.ChainedRequestInput;
3import com.generated.api.myjavaapi.client.api.Handlers.Response;
4import com.generated.api.myjavaapi.client.api.Handlers.ApiResponse;
5import com.generated.api.myjavaapi.client.model.ApiError;
6
7public class TryCatchInterceptor<Input> implements Interceptor<Input> {
8    @Override
9    public Response handle(ChainedRequestInput<Input> input) {
10        try {
11            return input.getChain().next(input);
12        } catch (Exception e) {
13            return ApiResponse.builder()
14                    .statusCode(500)
15                    .body(ApiError.builder()
16                            .errorMessage(e.getMessage())
17                            .build().toJson())
18                    .build();
19        }
20    }
21}

Interceptors are permitted to mutate the "interceptor context", which is a Map<String, Object>. Each interceptor in the chain, and the final handler, can access this context:

1public class IdentityInterceptor<Input> implements Interceptor<Input> {
2    @Override
3    public Response handle(ChainedRequestInput<Input> input) {
4        input.getInterceptorContext().put("AuthenticatedUser", this.getAuthenticatedUser(input.getEvent()));
5        return input.getChain().next(input);
6    }
7}

Interceptors can also mutate the response returned by the handler chain. An example use case might be adding cross-origin resource sharing headers:

1public static class AddCorsHeadersInterceptor<Input> implements Interceptor<Input> {
2    @Override
3    public Response handle(ChainedRequestInput<Input> input) {
4        Response res = input.getChain().next(input);
5        res.getHeaders().put("Access-Control-Allow-Origin", "*");
6        res.getHeaders().put("Access-Control-Allow-Headers", "*");
7        return res;
8    }
9}

Interceptors with Dependency Injection

Interceptors referenced by the @Interceptors annotation must be constructable with no arguments. If more complex instantiation of your interceptor is required (for example if you are using dependency injection or wish to pass configuration to your interceptor), you may instead override the getInterceptors method in your handler:

1public class SayHelloHandler extends SayHello {
2    @Override
3    public List<Interceptor<SayHelloInput>> getInterceptors() {
4        return Arrays.asList(
5                new MyConfiguredInterceptor<>(42),
6                new MyOtherConfiguredInterceptor<>("configuration"));
7    }
8
9    @Override
10    public SayHelloResponse handle(SayHelloRequestInput sayHelloRequestInput) {
11        return SayHello200Response.of(HelloResponse.builder()
12                .message(String.format("Hello %s!", sayHelloRequestInput.getInput().getRequestParameters().getName()))
13                .build());
14    }
15}

Other Details

Workspaces and OpenApiGatewayTsProject

OpenApiGatewayTsProject can be used as part of a monorepo using YARN/NPM/PNPM workspaces. When used in a monorepo, a dependency is established between OpenApiGatewayTsProject and the generated typescript client, which is expected to be managed by the parent monorepo (ie both OpenApiGatewayTsProject and the generated typescript client are parented by the monorepo).

During initial project synthesis, the dependency between OpenApiGatewayTsProject and the generated client is established via workspace configuration local to OpenApiGatewayTsProject, since the parent monorepo will not have updated to include the new packages in time for the initial "install".

When the package manager is PNPM, this initial workspace is configured by creating a local pnpm-workspace.yaml file, and thus if you specify your own for an instance of OpenApiGatewayTsProject, synthesis will fail. It is most likely that you will not need to define this file locally in OpenApiGatewayTsProject since the monorepo copy should be used to manage all packages within the repo, however if managing this file at the OpenApiGatewayTsProject level is required, please use the pnpmWorkspace property of OpenApiGatewayTsProject.

Customising Generated Client Projects

By default, the generated clients are configured automatically, including project names. You can customise the generated client code using the <language>ProjectOptions properties when constructing your projen project.

Python Shared Virtual Environment

For adding dependencies between python projects within a monorepo you can use a single shared virtual environment, and install your python projects into that environment with pip install --editable . in the dependee. The generated python client will automatically do this if it detects it is within a monorepo.

The following example shows how to configure the generated client to use a shared virtual environment:

1const api = new OpenApiGatewayTsProject({
2  parent: monorepo,
3  name: 'api',
4  outdir: 'packages/api',
5  defaultReleaseBranch: 'main',
6  clientLanguages: [ClientLanguage.PYTHON],
7  pythonClientOptions: {
8    moduleName: 'my_api_python',
9    name: 'my_api_python',
10    authorName: 'jack',
11    authorEmail: 'me@example.com',
12    version: '1.0.0',
13    venvOptions: {
14      // Directory relative to the generated python client (in this case packages/api/generated/python)
15      envdir: '../../../../.env',
16    },
17  },
18});
19
20new PythonProject({
21  parent: monorepo,
22  outdir: 'packages/my-python-lib',
23  moduleName: 'my_python_lib',
24  name: 'my_python_lib',
25  authorName: 'jack',
26  authorEmail: 'me@example.com',
27  version: '1.0.0',
28  venvOptions: {
29    // Directory relative to the python lib (in this case packages/my-python-lib)
30    envdir: '../../.env',
31  },
32  // Generated client can be safely cast to a PythonProject
33  deps: [(api.generatedClients[ClientLanguage.PYTHON] as PythonProject).moduleName],
34});

Java API Lambda Handlers

To build your lambda handlers in Java, it's recommended to create a separate JavaProject in your .projenrc. This needs to build a "super jar" with all of your dependencies packed into a single jar. You can use the maven-shade-plugin to achieve this (see the java lambda docs for details). You'll need to add a dependency on the generated java client for the handler wrappers. For example, your .projenrc.ts might look like:

1const api = new OpenApiGatewayTsProject({
2  parent: monorepo,
3  name: '@my-test/api',
4  outdir: 'packages/api',
5  defaultReleaseBranch: 'main',
6  clientLanguages: [ClientLanguage.JAVA],
7});
8
9const apiJavaClient = (api.generatedClients[ClientLanguage.JAVA] as JavaProject);
10
11const javaLambdaProject = new JavaProject({
12  parent: monorepo,
13  outdir: 'packages/java-lambdas',
14  artifactId: "my-java-lambdas",
15  groupId: "com.mycompany",
16  name: "javalambdas",
17  version: "1.0.0",
18  // Add a dependency on the java client
19  deps: [`${apiJavaClient.pom.groupId}/${apiJavaClient.pom.artifactId}@${apiJavaClient.pom.version}`],
20});
21
22// Set up the dependency on the generated lambda client
23monorepo.addImplicitDependency(javaLambdaProject, apiJavaClient);
24javaLambdaProject.pom.addRepository({
25  url: `file://../api/generated/java/dist/java`,
26  id: 'java-api-client',
27});
28
29// Use the maven-shade-plugin as part of the maven package task
30javaLambdaProject.pom.addPlugin('org.apache.maven.plugins/maven-shade-plugin@3.2.2', {
31  configuration: {
32    createDependencyReducedPom: false,
33    finalName: 'my-java-lambdas',
34  },
35  executions: [{
36    id: 'shade-task',
37    phase: 'package', // <- NB "phase" is supported in projen ^0.61.37
38    goals: ['shade'],
39  }],
40});
41
42// Build the "super jar" as part of the project's package task
43javaLambdaProject.packageTask.exec('mvn clean install');

You can then implement your lambda handlers in your java-lambdas project using the generated lambda handler wrappers (see above).

Finally, you can create a lambda function in your CDK infrastructure which points to the resultant "super jar":

1new Api(this, 'JavaApi', {
2  integrations: {
3    sayHello: {
4      function: new Function(this, 'SayHelloJava', {
5        code: Code.fromAsset('../java-lambdas/target/my-java-lambdas.jar'),
6        handler: 'com.mycompany.SayHelloHandler',
7        runtime: Runtime.JAVA_11,
8        timeout: Duration.seconds(30),
9      }),
10    },
11  },
12});

Note that to ensure the jar is built before the CDK infrastructure which consumes it, you must add a dependency, eg:

1monorepo.addImplicitDependency(infra, javaLambdaProject);

AWS WAFv2 Web ACL

By default, a Web ACL is deployed and attached to your API Gateway Rest API with the "AWSManagedRulesCommonRuleSet", which provides protection against exploitation of a wide range of vulnerabilities, including some of the high risk and commonly occurring vulnerabilities described in OWASP publications such as OWASP Top 10.

You can customise the Web ACL configuration via the webAclOptions of your Api CDK construct, eg:

1export class SampleApi extends Api {
2  constructor(scope: Construct, id: string) {
3    super(scope, id, {
4      integrations: { ... },
5      webAclOptions: {
6        // Allow access only to specific CIDR ranges
7        cidrAllowList: {
8          cidrType: 'IPV4',
9          cidrRanges: ['1.2.3.4/5'],
10        },
11        // Pick from the set here: https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-list.html
12        managedRules: [
13          { vendor: 'AWS', name: 'AWSManagedRulesSQLiRuleSet' },
14        ],
15      },
16    });
17  }
18}

You can remove the Web ACL entirely with webAclOptions: { disable: true } - you may wish to use this if you'd like to set up a Web ACL yourself with more control over the rules.

Smithy IntelliJ Plugin

The Smithy-based projects are compatible with the Smithy IntelliJ Plugin, which provides syntax highlighting and auto-complete for your Smithy model. To make use of it, perform the following steps:

• Install the "Smithy" plugin (under Preferences -> Plugins)
• Right-click on the smithy/build.gradle file in your Smithy API project
• Select "Link Gradle Project"

Tagging Operations

Operations can be grouped together into logical collections via tags. This can be achieved in Smithy with the @tags trait:

1@tags(["pets", "users"])
2operation PurchasePet {
3  ...
4}

Or in OpenAPI using the tags property:

1paths:
2  /pets/purchase:
3    post:
4      operationId: purchasePet
5      tags:
6        - pets
7        - users
8      ...

When multiple tags are used, the "first" tag is considered to be the API that the operation belongs to, so in the generated client, the above example operation would be included in the PetsApi client but not the UsersApi client.

Multiple tags are still useful for documentation generation, for example DocumentationFormat.HTML_REDOC will group operations by tag in the side navigation bar.

If you would like to introduce tags without breaking existing clients, we recommend first adding a tag named default to all operations.

⚠️ Important Note: Smithy versions below 1.28.0 sort tags in alphabetical order and so the "first" tag will be the earliest in the alphabet. Therefore, if using tags with older versions of Smithy, we recommend prefixing your desired first tag with an underscore (for example _default). This is rectified in 1.28.0, where tag order from the @tags trait is preserved.

Breaking Changes

• v0.14.0 - see https://github.com/aws/aws-prototyping-sdk/pull/280
  • Moved smithy model files from model directory to smithy/src/main/smithy - please move these manually as part of upgrading to 0.14.0, and delete your model directory when done.
  • Moved smithy gradle files from smithy-build directory to smithy - if you have added any dependencies to your smithy-build/build.gradle file you will need to copy them across into smithy/build.gradle (note dependencies in the new gradle file start with implementation rather than smithy).
  • Deprecated gradleWrapperPath option on SmithApiGateway projects in favour of ignoreGradleWrapper: false - the gradle wrapper in smithy directory is always used (and generated automatically if not found). If you used a custom gradle wrapper, copy it into the smithy directory, set ignoreGradleWrapper: false and check it in to your repository.