chore(apigatewayv2): review readme

packages/@aws-cdk/aws-apigatewayv2-alpha/README.md

@@ -46,6 +46,8 @@ This module supports features under [API Gateway v2](https://docs.aws.amazon.com
 that lets users set up Websocket and HTTP APIs.
 REST APIs can be created using the `aws-cdk-lib/aws-apigateway` module.
 
+HTTP and Websocket APIs use the same CloudFormation resources under the hood. However, this module separates them into two separate constructs for a more efficient abstraction since there are a number of CloudFormation properties that specifically apply only to each type of API.
+
 ## HTTP API
 
 HTTP APIs enable creation of RESTful APIs that integrate with AWS Lambda functions, known as Lambda proxy integration,
@@ -65,16 +67,15 @@ integration, HTTP proxy integration and, AWS service integrations, also known as
 [Configuring integrations](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations.html).
 
 Integrations are available at the `aws-apigatewayv2-integrations` module and more information is available in that module.
-As an early example, the following code snippet configures a route `GET /books` with an HTTP proxy integration all
-configures all other HTTP method calls to `/books` to a lambda proxy.
+As an early example, we have a website for a bookstore where the following code snippet configures a route `GET /books` with an HTTP proxy integration. All other HTTP method calls to `/books` route to a default lambda proxy for the bookstore.
 
 ```ts
 import { HttpUrlIntegration, HttpLambdaIntegration } from '@aws-cdk/aws-apigatewayv2-integrations-alpha';
 
 const getBooksIntegration = new HttpUrlIntegration('GetBooksIntegration', 'https://get-books-proxy.example.com');
 
-declare const booksDefaultFn: lambda.Function;
-const booksDefaultIntegration = new HttpLambdaIntegration('BooksIntegration', booksDefaultFn);
+declare const bookStoreDefaultFn: lambda.Function;
+const bookStoreDefaultIntegration = new HttpLambdaIntegration('BooksIntegration', bookStoreDefaultFn);
 
 const httpApi = new apigwv2.HttpApi(this, 'HttpApi');
 
@@ -86,7 +87,7 @@ httpApi.addRoutes({
 httpApi.addRoutes({
   path: '/books',
   methods: [ apigwv2.HttpMethod.ANY ],
-  integration: booksDefaultIntegration,
+  integration: bookStoreDefaultIntegration,
 });
 ```
 
@@ -310,9 +311,16 @@ The following code creates a `VpcLink` to a private VPC.
 
 ```ts
 import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as elb from 'aws-cdk-lib/aws-elasticloadbalancingv2';
+import { HttpAlbIntegration } from '@aws-cdk/aws-apigatewayv2-integrations-alpha';
 
 const vpc = new ec2.Vpc(this, 'VPC');
+const alb = new elb.ApplicationLoadBalancer(this, 'AppLoadBalancer', { vpc });
+
 const vpcLink = new apigwv2.VpcLink(this, 'VpcLink', { vpc });
+
+// Creating an HTTP ALB Integration:
+const albIntegration = new HttpAlbIntegration('ALBIntegration', alb.listeners[0], {});
 ```
 
 Any existing `VpcLink` resource can be imported into the CDK app via the `VpcLink.fromVpcLinkAttributes()`.

packages/@aws-cdk/aws-apigatewayv2-authorizers-alpha/README.md

@@ -33,19 +33,19 @@
 ## Introduction
 
 API Gateway supports multiple mechanisms for controlling and managing access to your HTTP API. They are mainly
-classified into Lambda Authorizers, JWT authorizers and standard AWS IAM roles and policies. More information is
+classified into Lambda Authorizers, JWT authorizers, and standard AWS IAM roles and policies. More information is
 available at [Controlling and managing access to an HTTP
 API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control.html).
 
 ## HTTP APIs
 
-Access control for Http Apis is managed by restricting which routes can be invoked via.
+Access control for HTTP APIs is managed by restricting which routes can be invoked via.
 
-Authorizers and scopes can either be applied to the api, or specifically for each route.
+Authorizers and scopes can either be applied to the API, or specifically for each route.
 
 ### Default Authorization
 
-When using default authorization, all routes of the api will inherit the configuration.
+When using default authorization, all routes of the API will inherit the configuration.
 
 In the example below, all routes will require the `manage:books` scope present in order to invoke the integration.
 
@@ -65,12 +65,12 @@ const api = new apigwv2.HttpApi(this, 'HttpApi', {
 
 ### Route Authorization
 
-Authorization can also configured for each Route. When a route authorization is configured, it takes precedence over default authorization.
+Authorization can also be configured for each Route. When a route authorization is configured, it takes precedence over default authorization.
 
 The example below showcases default authorization, along with route authorization. It also shows how to remove authorization entirely for a route.
 
 - `GET /books` and `GET /books/{id}` use the default authorizer settings on the api
-- `POST /books` will require the [write:books] scope
+- `POST /books` will require the `['write:books']` scope
 - `POST /login` removes the default authorizer (unauthenticated route)
 
 ```ts
@@ -120,7 +120,7 @@ JWT authorizers allow the use of JSON Web Tokens (JWTs) as part of [OpenID Conne
 
 When configured, API Gateway validates the JWT submitted by the client, and allows or denies access based on its content.
 
-The location of the token is defined by the `identitySource` which defaults to the http `Authorization` header. However it also
+The location of the token is defined by the `identitySource` which defaults to the HTTP `Authorization` header. However it also
 [supports a number of other options](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html#http-api-lambda-authorizer.identity-sources).
 It then decodes the JWT and validates the signature and claims, against the options defined in the authorizer and route (scopes).
 For more information check the [JWT Authorizer documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html).
@@ -150,7 +150,7 @@ api.addRoutes({
 
 #### User Pool Authorizer
 
-User Pool Authorizer is a type of JWT Authorizer that uses a Cognito user pool and app client to control who can access your Api. After a successful authorization from the app client, the generated access token will be used as the JWT.
+User Pool Authorizer is a type of JWT Authorizer that uses a Cognito user pool and app client to control who can access your API. After a successful authorization from the app client, the generated access token will be used as the JWT.
 
 Clients accessing an API that uses a user pool authorizer must first sign in to a user pool and obtain an identity or access token.
 They must then use this token in the specified `identitySource` for the API call. More information is available at [using Amazon Cognito user

packages/@aws-cdk/aws-apigatewayv2-integrations-alpha/README.md

@@ -34,8 +34,8 @@ Integrations connect a route to backend resources. HTTP APIs support Lambda prox
 Lambda integrations enable integrating an HTTP API route with a Lambda function. When a client invokes the route, the
 API Gateway service forwards the request to the Lambda function and returns the function's response to the client.
 
-The API Gateway service will invoke the lambda function with an event payload of a specific format. The service expects
-the function to respond in a specific format. The details on this format is available at [Working with AWS Lambda
+The API Gateway service will invoke the Lambda function with an event payload of a specific format. The service expects
+the function to respond in a specific format. The details on this format are available at [Working with AWS Lambda
 proxy integrations](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
 
 The following code configures a route `GET /books` with a Lambda proxy integration.
@@ -204,11 +204,11 @@ WebSocket integrations connect a route to backend resources. The following integ
 ### Lambda WebSocket Integration
 
 Lambda integrations enable integrating a WebSocket API route with a Lambda function. When a client connects/disconnects
-or sends message specific to a route, the API Gateway service forwards the request to the Lambda function
+or sends a message specific to a route, the API Gateway service forwards the request to the Lambda function
 
-The API Gateway service will invoke the lambda function with an event payload of a specific format.
+The API Gateway service will invoke the Lambda function with an event payload of a specific format.
 
-The following code configures a `sendmessage` route with a Lambda integration
+The following code configures a `sendMessage` route with a Lambda integration
 
 ```ts
 import { WebSocketLambdaIntegration } from '@aws-cdk/aws-apigatewayv2-integrations-alpha';
@@ -221,7 +221,7 @@ new apigwv2.WebSocketStage(this, 'mystage', {
 });
 
 declare const messageHandler: lambda.Function;
-webSocketApi.addRoute('sendmessage', {
+webSocketApi.addRoute('sendMessage', {
   integration: new WebSocketLambdaIntegration('SendMessageIntegration', messageHandler),
 });
 ```