Merge pull request #15052 from patriot1burke/aws-lambda-rest-api

Reorg and docs for aws lambda and HTTP  (API Gateway HTTP vs. REST API)

bom/application/pom.xml

@@ -1703,12 +1703,12 @@
             </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
-                <artifactId>quarkus-amazon-lambda-http-v1</artifactId>
+                <artifactId>quarkus-amazon-lambda-rest</artifactId>
                 <version>${project.version}</version>
             </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
-                <artifactId>quarkus-amazon-lambda-http-v1-deployment</artifactId>
+                <artifactId>quarkus-amazon-lambda-rest-deployment</artifactId>
                 <version>${project.version}</version>
             </dependency>
             <dependency>

devtools/bom-descriptor-json/pom.xml

@@ -135,7 +135,7 @@
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-amazon-lambda-http-v1</artifactId>
+            <artifactId>quarkus-amazon-lambda-rest</artifactId>
             <version>${project.version}</version>
             <type>pom</type>
             <scope>test</scope>

docs/pom.xml

@@ -173,7 +173,7 @@
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-amazon-lambda-http-v1-deployment</artifactId>
+            <artifactId>quarkus-amazon-lambda-rest-deployment</artifactId>
             <version>${project.version}</version>
             <type>pom</type>
             <scope>test</scope>

docs/src/main/asciidoc/amazon-lambda-http.adoc

@@ -3,18 +3,22 @@ This guide is maintained in the main Quarkus repository
 and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
 ////
-= Quarkus - Amazon Lambda with RESTEasy, Undertow, or Vert.x Web 
+= Quarkus - Amazon Lambda with RESTEasy, Undertow, or Vert.x Web
 :extension-status: preview
 
 include::./attributes.adoc[]
 
-The `quarkus-amazon-lambda-http` extension allows you to write microservices with RESTEasy (JAX-RS),
-Undertow (servlet), Vert.x Web, link:funqy-http[Funqy HTTP] or any other Quarkus HTTP API that runs on top of Vert.x Web
-and deploy them to Amazon Lambda
-using https://aws.amazon.com/api-gateway/[Amazon's API Gateway] and https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html[Amazon's SAM framework].
+With Quarkus you can deploy your favorite Java HTTP frameworks as Amazon Lambda's using either the https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html[AWS Gateway HTTP API]
+or https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html[AWS Gateway REST API].  This means that you can deploy your microservices written with RESTEasy (JAX-RS),
+Undertow (servlet), Vert.x Web, link:funqy-http[Funqy HTTP] or any other Quarkus HTTP framework as an AWS Lambda.
 
 You can deploy your Lambda as a pure Java jar, or you can compile your project to a native image and deploy that for a smaller
-memory footprint and startup time.
+memory footprint and startup time.  Our integration also generates SAM deployment files that can be consumed by https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html[Amazon's SAM framework].
+
+Quarkus has a different extension for each Gateway API.  The HTTP Gateway API is implemented within the `quarkus-amazon-lambda-http` extension.
+The REST Gateway API is implemented within the `quarkus-amazon-lambda-rest` extension.  If you are confused on which Gateway product to use,
+Amazon has a https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html[great guide] to help you navigate this decision.
+
 
 include::./status-include.adoc[]
 
@@ -42,7 +46,7 @@ for installing AWS SAM CLI.
 
 Create the Quarkus AWS Lambda maven project using our Maven Archetype.
 
-
+If you want to use the AWS Gateway HTTP API, generate your project with this script:
 [source,bash,subs=attributes+]
 ----
 mvn archetype:generate \
@@ -51,8 +55,15 @@ mvn archetype:generate \
        -DarchetypeVersion={quarkus-version}
 ----
 
-NOTE: This extension has recently been upgraded to use API Gateway V2.  If you need to still use V1 of the API Gateway
-use the `quarkus-amazon-lambda-http-v1` extension instead.
+If you want to use the AWS Gateway REST API, generate your project with this script:
+[source,bash,subs=attributes+]
+----
+mvn archetype:generate \
+       -DarchetypeGroupId=io.quarkus \
+       -DarchetypeArtifactId=quarkus-amazon-lambda-rest-archetype \
+       -DarchetypeVersion={quarkus-version}
+----
+
 
 == Build and Deploy
 
@@ -86,7 +97,7 @@ Lambda requires linux binaries.  You can do this by passing this property to you
 
 == Extra Build Generated Files
 
-After you run the build, there are a few extra files generated by the `quarkus-amazon-lambda` extension.  These files
+After you run the build, there are a few extra files generated by the quarkus lambda extension you are using.  These files
 are in the the build directory:  `target/` for maven, `build/` for gradle.
 
 * `function.zip` - lambda deployment file
@@ -161,31 +172,20 @@ sam deploy -t target/sam.native.yaml -g
 == Examine the POM
 
 There is nothing special about the POM other than the inclusion of the `quarkus-amazon-lambda-http` extension
-as a dependencies.  The extension automatically generates everything you might need for your lambda deployment.
+(if you are deploying an AWS Gateway HTTP API) or the `quarkus-amazon-lambda-rest` extension (if you are deploy an AWS Gateway REST API).
+These extensions automatically generate everything you might need for your lambda deployment.
 
 Also, at least in the generated maven archetype `pom.xml`, the `quarkus-resteasy`, `quarkus-vertx-web`, and `quarkus-undertow`
 dependencies are all optional.  Pick which http framework(s) you want to use (JAX-RS, Vertx Web, and/or Servlet) and
 remove the other dependencies to shrink your deployment.
 
 === Examine sam.yaml
 
-The `sam.yaml` syntax is beyond the scope of this document.  There's a couple of things to note though that are particular
-to the `quarkus-amazon-lambda-http` extension.
-
-Amazon's API Gateway assumes that HTTP response bodies are text unless you explicitly tell it which media types are
-binary through configuration.  To make things easier, the Quarkus extension forces a binary (base 64) encoding of all
-HTTP response messages and the `sam.yaml` file must configure the API Gateway to assume all media types are binary:
-
-[source, subs=attributes+]
-----
-  Globals:
-    Api:
-      EndpointConfiguration: REGIONAL
-      BinaryMediaTypes:
-        - "*/*"
-----
+The `sam.yaml` syntax is beyond the scope of this document.  There's a couple of things that must be highlighted just in case you are
+going to craft your own custom `sam.yaml` deployment files.
 
-Another thing to note is that for pure Java lambda deployments, do not change the Lambda handler name.
+The first thing to note is that for pure Java lambda deployments require a specific handler class.
+Do not change the Lambda handler name.
 
 [source, subs=attributes+]
 ----
@@ -194,10 +194,9 @@ Another thing to note is that for pure Java lambda deployments, do not change th
         Runtime: java11
 ----
 
-This particular handler handles all the intricacies of integrating with the Quarkus runtime.  So you must use that
-handler.
+This handler is a bridge between the lambda runtime and the Quarkus HTTP framework you are using (JAX-RS, Servlet, etc.)
 
-Finally, there's an environment variable that must be set for native GraalVM deployments.  If you look at `sam.native.yaml`
+If you want to go native, there's an environment variable that must be set for native GraalVM deployments.  If you look at `sam.native.yaml`
 you'll see this:
 
 [source, subs=attributes+]
@@ -209,6 +208,20 @@ you'll see this:
 
 This environment variable resolves some incompatibilities between Quarkus and the Amazon Lambda Custom Runtime environment.
 
+Finally, there is one specific thing for AWS Gateway REST API deployments.
+That API assumes that HTTP response bodies are text unless you explicitly tell it which media types are
+binary through configuration.  To make things easier, the Quarkus extension forces a binary (base 64) encoding of all
+HTTP response messages and the `sam.yaml` file must configure the API Gateway to assume all media types are binary:
+
+[source, subs=attributes+]
+----
+  Globals:
+    Api:
+      EndpointConfiguration: REGIONAL
+      BinaryMediaTypes:
+        - "*/*"
+----
+
 == Tracing with AWS XRay and GraalVM
 
 If you are building native images, and want to use https://aws.amazon.com/xray[AWS X-Ray Tracing] with your lambda

extensions/amazon-lambda-http-v1/deployment/pom.xml → extensions/amazon-lambda-rest/deployment/pom.xml

@@ -6,13 +6,13 @@
 
     <parent>
         <groupId>io.quarkus</groupId>
-        <artifactId>quarkus-amazon-lambda-http-v1-parent</artifactId>
+        <artifactId>quarkus-amazon-lambda-rest-parent</artifactId>
         <version>999-SNAPSHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 
-    <artifactId>quarkus-amazon-lambda-http-v1-deployment</artifactId>
-    <name>Quarkus - Amazon Lambda HTTP V1 - Deployment</name>
+    <artifactId>quarkus-amazon-lambda-rest-deployment</artifactId>
+    <name>Quarkus - Amazon Lambda AWS Gateway REST API - Deployment</name>
 
     <dependencies>
         <dependency>
@@ -29,7 +29,7 @@
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-amazon-lambda-http-v1</artifactId>
+            <artifactId>quarkus-amazon-lambda-rest</artifactId>
         </dependency>
     </dependencies>
     <build>

extensions/amazon-lambda-http-v1/maven-archetype/pom.xml → extensions/amazon-lambda-rest/maven-archetype/pom.xml

@@ -3,14 +3,14 @@
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>quarkus-amazon-lambda-http-v1-parent</artifactId>
+        <artifactId>quarkus-amazon-lambda-rest-parent</artifactId>
         <groupId>io.quarkus</groupId>
         <version>999-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
-    <artifactId>quarkus-amazon-lambda-http-v1-archetype</artifactId>
-    <name>Quarkus - Amazon Lambda HTTP V1 - Archetype</name>
+    <artifactId>quarkus-amazon-lambda-rest-archetype</artifactId>
+    <name>Quarkus - Amazon Lambda AWS Gateway REST API - Archetype</name>
     <packaging>maven-archetype</packaging>
 
     <build>

extensions/amazon-lambda-http-v1/maven-archetype/src/main/resources/archetype-resources/pom.xml → extensions/amazon-lambda-rest/maven-archetype/src/main/resources/archetype-resources/pom.xml

@@ -54,7 +54,7 @@
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-amazon-lambda-http-v1</artifactId>
+            <artifactId>quarkus-amazon-lambda-rest</artifactId>
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>

extensions/amazon-lambda-http-v1/pom.xml → extensions/amazon-lambda-rest/pom.xml

@@ -11,9 +11,8 @@
         <relativePath>../pom.xml</relativePath>
     </parent>
 
-    <artifactId>quarkus-amazon-lambda-http-v1-parent</artifactId>
-    <name>Quarkus - Amazon Lambda HTTP V1</name>
-    <!-- Deprecated support for API Gateway 1.0 message format and configuration -->
+    <artifactId>quarkus-amazon-lambda-rest-parent</artifactId>
+    <name>Quarkus - Amazon Lambda AWS Gateway REST API</name>
     <packaging>pom</packaging>
 
     <modules>

extensions/amazon-lambda-http-v1/runtime/pom.xml → extensions/amazon-lambda-rest/runtime/pom.xml

@@ -6,14 +6,13 @@
 
     <parent>
         <groupId>io.quarkus</groupId>
-        <artifactId>quarkus-amazon-lambda-http-v1-parent</artifactId>
+        <artifactId>quarkus-amazon-lambda-rest-parent</artifactId>
         <version>999-SNAPSHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 
-    <artifactId>quarkus-amazon-lambda-http-v1</artifactId>
-    <name>Quarkus - Amazon Lambda HTTP V1- Runtime</name>
-    <description>Deprecated API Gateway V1 api: Allow applications written for any Quarkus HTTP API to run in AWS Lambda</description>
+    <artifactId>quarkus-amazon-lambda-rest</artifactId>
+    <name>Quarkus - Amazon Lambda AWS Gateway REST API- Runtime</name>
 
     <dependencies>
         <dependency>

extensions/amazon-lambda-http-v1/runtime/src/main/resources/META-INF/quarkus-extension.yaml → extensions/amazon-lambda-rest/runtime/src/main/resources/META-INF/quarkus-extension.yaml

@@ -1,5 +1,5 @@
 ---
-name: "AWS Lambda HTTP V1 (deprecated)"
+name: "AWS Lambda Gateway REST API"
 metadata:
   keywords:
   - "lambda"

extensions/pom.xml

@@ -152,9 +152,10 @@
         <!-- Integrations -->
         <module>amazon-lambda</module>
         <module>amazon-lambda-xray</module>
+        <!-- AWS API Gateway HTTP API -->
         <module>amazon-lambda-http</module>
-        <!-- amazon-lambda-http-v1 is deprecated -->
-        <module>amazon-lambda-http-v1</module>
+        <!-- AWS API Gateway REST API -->
+        <module>amazon-lambda-rest</module>
         <module>amazon-services</module>
         <module>amazon-alexa</module>
         <module>azure-functions-http</module>

integration-tests/amazon-lambda-http-v1/pom.xml → integration-tests/amazon-lambda-rest/pom.xml

@@ -9,8 +9,8 @@
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
-    <artifactId>quarkus-integration-test-amazon-lambda-http-v1</artifactId>
-    <name>Quarkus - Integration Tests - Amazon Lambda HTTP V1</name>
+    <artifactId>quarkus-integration-test-amazon-lambda-rest</artifactId>
+    <name>Quarkus - Integration Tests - Amazon Lambda AWS Gateway REST API</name>
     <description>Module that contains Amazon Lambda related tests for RESTEasy</description>
     <dependencies>
         <dependency>
@@ -35,7 +35,7 @@
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-amazon-lambda-http-v1</artifactId>
+            <artifactId>quarkus-amazon-lambda-rest</artifactId>
         </dependency>
 
         <!-- test dependencies -->
@@ -53,7 +53,7 @@
         <!-- Minimal test dependencies to *-deployment artifacts for consistent build order -->
         <dependency>
             <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-amazon-lambda-http-v1-deployment</artifactId>
+            <artifactId>quarkus-amazon-lambda-rest-deployment</artifactId>
             <version>${project.version}</version>
             <type>pom</type>
             <scope>test</scope>

integration-tests/pom.xml

@@ -94,7 +94,7 @@
         <module>amazon-lambda-s3event</module>
         <module>amazon-lambda-stream-handler</module>
         <module>amazon-lambda-http</module>
-        <module>amazon-lambda-http-v1</module>
+        <module>amazon-lambda-rest</module>
         <module>amazon-lambda-http-resteasy</module>
         <module>container-image</module>
         <module>kubernetes</module>