aws-powertools / powertools-lambda-java

Powertools is a developer toolkit to implement Serverless best practices and increase developer velocity.
https://docs.powertools.aws.dev/lambda/java/
MIT No Attribution
287 stars 88 forks source link

RFC: Add Rest API Event Handler module #1103

Open jeromevdl opened 1 year ago

jeromevdl commented 1 year ago

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:

@Path("/todos")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class APIHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
    APIGatewayRestResolver resolver = new APIGatewayRestResolver(this);

    @GET
    private List<Todo> getTodos(@QueryParam("sort") String sort) {
        return Collections.singletonList(new Todo());
    }

    @Path("/{id}")
    @GET
    private Todo getTodo(@PathParam("id") String id) {
        return new Todo();
    }

    @POST
    private Todo createTodo(@HeaderParam("X-header-for-creation") String header, Todo todo) {
        return todo;
    }

    @Path("/{id}")
    @PUT
    private Todo updateTodo(@PathParam("id") String id, Todo todo) {
        return todo;
    }

    @Path("/{id}")
    @DELETE
    private void deleteTodo(@PathParam("id") String id) {
    }

    @Override
    public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent event, Context context) {
        return resolver.resolve(event, context);
    }
}

Drawbacks

Do we need additional dependencies? Impact performance/package size?

New module, with JAX-RS dependency (quite lightweight as it's just an API: 126 898 bytes)

Rationale and alternatives

Alternative frameworks/libraries:

Unresolved questions

jeromevdl commented 1 year ago

Note that we can also handle the APIGatewayV2HTTPEvent in the same way.

jeromevdl commented 1 year ago

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.

mriccia commented 1 year ago

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:

jeromevdl commented 1 year ago

⚠️ 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)?

msailes commented 1 year ago

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?

scottgerring commented 1 year ago

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.

scottgerring commented 1 year ago

We're actively choosing not to work on this for now and I am marking it as blocked to reflect that.