Open jeromevdl opened 1 year ago
Note that we can also handle the APIGatewayV2HTTPEvent in the same way.
jax-rs => jakarta-rs, see https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html But as we need to be compliant with Java 1.8, we must stay on jax-rs imports and cannot use later version than 2.1.6.
I really like this RFC, I agree on the jax-rs/jakarta-rs API compatibility and for me it is a must have. It will enable easy porting of code into Powertools, and the familiar API will reduce the developer friction. Few questions:
⚠️ JAX-RS is based on reflection, which is slow. As it is intended to be used with API Gateway and supposed to be fast (sync call), it's an important drawback.
Could we use compile-time weaving or annotation preprocessor (code generation)?
I think this is a really exciting idea. Lots of people are interested in running rest endpoints on Lambda.
If Powertools only supports a subsection of the standard, how can we help users understand whether their application would be supported or not?
Would there be a clear list of features / annotations which were yes / no?
For the moment we can steer users to existing integrations rather than reinventing the wheel. For instance:
This misses some of the functionality in the powertools for python (e.g. - supporting event from all the different possible sources - REST API GW, HTTP API GW, ALB, Lattice), but I think we should wait to see demand for this first.
We're actively choosing not to work on this for now and I am marking it as blocked to reflect that.
Key information
Summary
To fill the gap with Python and the REST API Handler module, we want to introduce a new module, to ease the integration with API Gateway requests (routing, cors, extracting parameters, ...).
Motivation
The integration between API GW and Lambda is probably the most common pattern used by AWS customers. Today, you can do it manually, which implies a lot of boilerplate code: routing, retrieving the headers & parameters & body of the request, deserialize the body, creating a response object (adding the cors headers), ... Or you can use frameworks that partially solve some of these features (ex: Spring routing). But there is not a single all-in-one easy-to-use framework, just like the Python version of this module.
If java was left aside for this kind of integration (because of cold starts), it should not anymore be the case with Snapstart. Having this easy integration would help our users focusing on the business side of their function and not the boilerplate code to make it work.
Proposal
The module should implement the JAX-RS API (at least partially), which is the Java standard to define REST APIs. See the javax.ws.rs doc and javax.ws.rs.core doc.
Here is an example of what it could look like for developers:
The module should handle the following annotations:
@GET
,@POST
,@PUT
,@DELETE
,@PATCH
http verbs@Path
on the classes and on methods@PathParam
,@QueryParam
,@HeaderParam
,@FormParam
, Nice to have :@MatrixParam, @CookieParam
. Parameters will be automatically extracted fromAPIGatewayProxyRequestEvent
@Consumes
&@Produces
to specify the headers in the responseThe module should be able to handle
javax.ws.rs.core.Response
object (and inner objects likeNewCookie
and others) and transform it into acom.amazonaws.services.lambda.runtime.eventsAPIGatewayProxyResponseEvent
.The module should be able to transform the exceptions (ex: BadRequestException, or InternalServerErrorException) into proper responses.
The module should be able to ease the CORS header: see #1029 and #831.
Drawbacks
New module, with JAX-RS dependency (quite lightweight as it's just an API: 126 898 bytes)
Rationale and alternatives
What other designs have been considered? Why not them? We could avoid the coupling with JAX-RS and have our own API (for example similar to what Python is providing). I believe the learning curve and the adoption will be easier by adopting such a standard. It makes the function easily readable and understandable.
What is the impact of not doing this? We can choose not to do this module and let people use their preferred framework but, unless I mistaken, there is not a single library that handles eveything with the same devx, and it should be much beneficial to have this layer on top of events/response and ease the routing, serialization, ...
Alternative frameworks/libraries:
Unresolved questions