How to return a "null" response for API Gateway REST event handler with enabled data validation?

[nlykkei]

Suppose I enable data validation for my APIGatewayRestResolver as follows:

app = APIGatewayRestResolver(enable_validation=True)

I want to convert the original response to something that's accepted by the data validater:

Original response:

Response(status_code=HTTPStatus.OK, content_type=content_types.TEXT_PLAIN, body="")

My first attempt is as follows:

@app.get("/hello")
@tracer.capture_method
def get_hello() -> Response[None]:
    return Response(status_code=HTTPStatus.OK, content_type=content_types.APPLICATION_JSON, body=None)

It works, as a null is returned:

However, it feel "hacked", as None is not Pydantic BaseModel, which is what the data validation feature expects?

[heitorlessa]

Hey @nlykkei! None is technically null when serialized/deserialized to/from JSON.

I don't have context on the consumer, but I'd prefer always having a sane default like an empty {} which is also valid JSON instead.

[heitorlessa]

Thanks for your patience, Nicolas! I'm gonna break my answer in categories to make sure I don't miss any of your questions.

Repro

• GET sample: https://pm5mz0wx61.execute-api.eu-west-1.amazonaws.com/Prod/nocontent
• Swagger UI: https://pm5mz0wx61.execute-api.eu-west-1.amazonaws.com/Prod/swagger#/default/no_content_nocontent_get

How can I return an empty response in this case?

My recommendation is to stick with -> Response[None] along with a Response return that doesn't pass a body argument. That will match your expectations and the RFC 7231 in sending a Content-Length of 0 (no body).

Example:

@app.get("/nocontent")
def no_content() -> Response[None]:
    return Response(
        status_code=HTTPStatus.NO_CONTENT.value, content_type=content_types.TEXT_PLAIN
    )

This however doesn't generate an optimal OpenAPI schema. Customizing OpenAPI parameters leads to the expected schema you shared:

@app.get(
    "/nocontent",
    responses={
        204: OpenAPIResponse(
            description="204 No Content - returned when up to date",
            content={content_types.TEXT_PLAIN: {}},
        )
    },
)
def no_content() -> Response[dict]:
    return Response(
        status_code=HTTPStatus.NO_CONTENT.value, content_type=content_types.TEXT_PLAIN
    )

...Data Validation and auto-generate OpenAPI Spec

But it can also be generated without enabling that feature?

No. For context, we've tried splitting them and rely on a 3P dependency (apispec) however it quickly led to complications to get Pydantic and data validation working well together.

Ideas

Besides extending the documentation to cover this common use case, we could either A/ create a special return type that would automatically generate an OpenAPI Schema, or B) offer a subclass of OpenAPIResponse like NoContentOpenAPIResponse to handle this more graciously.

Let us know your thoughts, and let me know if I missed anything.

---

complete sample

from aws_lambda_powertools import Logger, Tracer
from aws_lambda_powertools.event_handler import (
    APIGatewayRestResolver,
    Response,
    content_types,
)
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing import LambdaContext
from http import HTTPStatus
from aws_lambda_powertools.event_handler.openapi.types import (
    OpenAPIResponse,
)

tracer = Tracer()
logger = Logger()
app = APIGatewayRestResolver(enable_validation=True)
app.enable_swagger(path="/swagger")


@app.get(
    "/nocontent",
    responses={
        204: OpenAPIResponse(
            description="204 No Content - returned when up to date",
            content={content_types.TEXT_PLAIN: {}},
        )
    },
)
def no_content() -> Response[None]:
    return Response(
        status_code=HTTPStatus.NO_CONTENT.value, content_type=content_types.TEXT_PLAIN
    )


@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
@tracer.capture_lambda_handler
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    ret = app.resolve(event, context)

    logger.info("Returning response", response=ret)
    return ret

raw response

{
    "statusCode": 204,
    "body": null,
    "isBase64Encoded": false,
    "multiValueHeaders": {
      "Content-Type": [
        "text/plain"
      ]
    }
  }

[nlykkei]

Thank you for your elaborate clarification @heitorlessa!

I see it's working as expected 🎉 Thus, I have the following comments:

• The solution is very "hacky", and others will likely ask this question in the future, as HTTP 202 and HTTP 204 are very common status codes.
• I don't think you need to take the value of the Enum, as it's an IntEnum: status_code=HTTPStatus.NO_CONTENT.value
• For responses with no body (Content-Length: 0), should they even specify a Content-Type? If they have to specify one, then it's not used for anything?
• I don't know whether Swagger UI has a way of communicating to clients that no content is returned. It seems odd to display an example value ("string"), when nothing will ever be returned.
• I think both of your suggestions are good, thus I think I prefer NoContentOpenAPIResponse 💡

[nlykkei]

Hi again, @heitorlessa!

I checked how an empty response is normally rendered in Swagger UI:

  responses:
    "200":
      description: 200 response
      content: {}

So, you see a clear difference: no media type is listed, no example is shown, etc.

Thus, the current solution is functionally correct, but has different semantics for Swagger UI

[nlykkei]

Actually, be setting content={}, the Swagger UI is correctly rendered:

@app.get(
    "/nocontent",
    responses={
        204: OpenAPIResponse(
            description="204 No Content - returned when up to date",
            content={},
        )
    },
)
def no_content() -> Response[None]:
    return Response(
        status_code=HTTPStatus.NO_CONTENT.value, content_type=content_types.TEXT_PLAIN
    )

No. For context, we've tried splitting them and rely on a 3P dependency (apispec) however it quickly led to complications to get Pydantic and data validation working well together.

I can generate OpenAPI spec with enable_validation=False, so are you sure your statement is true?

[heitorlessa]

I can generate OpenAPI spec with enable_validation=False, so are you sure your statement is true?

Nope, @leandrodamascena corrected me in private two hours ago; What I meant to say but clearly missed is that you will need pydantic as a dependency to use OpenAPI or data validation feature.

Personally, I wouldn't use the OpenAPI without the data validation to ensure correctness. That said, we should provide a less error prone way to get to HTTP 204, almost like def no_content() -> NoContent to both validate and ensure OpenAPI Spec w/o a Content-Type, without the need for an explicit responses={...}.

Please feel free to create a feature request so we can improve everyone's experience. A docs revamp on OpenAPI is in order too.