Use case
As a developer building serverless APIs with AWS Lambda Powertools, I need to handle file uploads (images, documents, PDFs, etc.) through my API endpoints with proper validation and OpenAPI documentation.
Currently, I can only handle JSON payloads and form data (application/x-www-form-urlencoded) but cannot process multipart/form-data file uploads. This forces me to:
- Manually parse multipart data - Complex, error-prone, and doesn't integrate with OpenAPI validation
- Use workarounds like base64-encoded JSON payloads - Inefficient and not standard
- Skip validation - Missing out on Powertools' automatic validation benefits
- Write custom OpenAPI schemas - Manual work that should be automated
Common scenarios I need to support:
- Profile image uploads - Users uploading avatar images
- Document processing - PDF uploads for analysis or conversion
- Batch file imports - CSV/Excel file uploads for data processing
- Multiple file uploads - Image galleries, document collections
- Mixed form data - File uploads with metadata (title, description, tags)
This is a standard web development requirement that other frameworks like FastAPI, Django, and Express.js handle seamlessly.
Solution/User Experience
Add a File parameter type that works seamlessly with the existing OpenAPI validation system, providing the same developer experience as Query, Header, and Form parameters.
Proposed Developer Experience:
Simple File Upload
from typing_extensions import Annotated
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import File
app = APIGatewayRestResolver(enable_validation=True)
@app.post("/upload")
def upload_file(file: Annotated[bytes, File(description="File to upload")]):
return {"file_size": len(file)}
**File Upload with Validation**
@app.post("/upload-image")
def upload_image(
file: Annotated[bytes, File(
description="Image file (max 5MB)",
min_length=1024, # Minimum 1KB
max_length=5242880, # Maximum 5MB
)]
):
return {"message": "Image uploaded successfully"}
**Multiple Files + Metadata**
from aws_lambda_powertools.event_handler.openapi.params import File, Form
@app.post("/gallery-upload")
def upload_gallery(
image1: Annotated[bytes, File(description="First image")],
image2: Annotated[bytes, File(description="Second image")],
title: Annotated[str, Form(description="Gallery title")],
description: Annotated[str, Form(description="Gallery description")]
):
return {
"gallery_title": title,
"images_uploaded": 2,
"total_size": len(image1) + len(image2)
}
### Alternative solutions
```markdownAcknowledgment
Use case
As a developer building serverless APIs with AWS Lambda Powertools, I need to handle file uploads (images, documents, PDFs, etc.) through my API endpoints with proper validation and OpenAPI documentation.
Currently, I can only handle JSON payloads and form data (application/x-www-form-urlencoded) but cannot process multipart/form-data file uploads. This forces me to:
Common scenarios I need to support:
This is a standard web development requirement that other frameworks like FastAPI, Django, and Express.js handle seamlessly.
Solution/User Experience
Add a
Fileparameter type that works seamlessly with the existing OpenAPI validation system, providing the same developer experience asQuery,Header, andFormparameters.Proposed Developer Experience:
Simple File Upload
Acknowledgment