Backend Documentation

Overview

This service provides a REST API for managing user-uploaded images. Metadata is stored in DynamoDB, while image files are stored in S3. The API generates presigned URLs to allow secure, temporary access to images.

Prerequisites

• AWS Lambda function -DynamoDB table:
  • Partition key: userId
  • Sort key: imageId
• S3 bucket for image storage
• API Gateway with JWT authorizer
• IAM permissions for DynamoDB and S3 operations

Implementation / Steps

1. API Gateway forwards requests to Lambda.
2. Authentication middleware extracts the user ID from the JWT.
3. Exception middleware standardizes all error responses.
4. Route handlers process requests using DynamoDB and S3.
5. Presigned URLs are generated when image access is required.

Key Takeaways

• Metadata and file storage are separated (DynamoDB vs S3).
• All endpoints require authentication.
• Presigned URLs prevent direct public access to S3.

Core Image API Endpoints

GET /images/{imageId}

Overview

Retrieve metadata and a temporary download URL for a single specific image belonging to the authenticated user.

Prerequisites

• Valid JWT token
• Image must exist for the user in DynamoDB

Implementation / Steps

1. Extract the authenticated user_id.
2. Query DynamoDB using userId and imageId.
3. Validate that the item exists.
4. Ensure required fields (tags, s3Key) are present.
5. Generate a presigned S3 URL for download.
6. Return tags and the download URL.

Key Takeaways

• Returns only user-owned images.
• Missing items result in a 404 error.
• Presigned URLs expire (default: 1 hour).

GET /images

Overview

Retrieve all images for the authenticated user, including metadata and download URLs.

Prerequisites

• Valid JWT token

Implementation / Steps

1. Extract the authenticated user_id.
2. Query DynamoDB using the partition key.
3. Sort results in descending order.
4. Generate presigned URLs for each image.
5. Validate and normalize the response data.
6. Convert non-JSON-compatible values (e.g., Decimal).

Key Takeaways

• Results are returned newest first.
• Each image includes a download URL.
• Data validation ensures consistent API responses.

PATCH /update-metadata

Overview

Update the tags or description associated with an existing image.

Prerequisites

• Valid JWT token
• Request body must include:
  • userId
  • imageId
  • tags

Implementation / Steps

1. Parse and validate the request body.
2. Identify the target item using userId and imageId.
3. Update the tags attribute in DynamoDB.
4. Return a success response.

Key Takeaways

• Tags are fully replaced, not appended.
• Invalid payloads result in a 400 error.

DELETE /image/{imageId}

Overview

Validates the image’s UUID and then deletes the image and corresponding metadata from S3 and DynamoDB.

Prerequisites

• Valid JWT token

Implementation / Steps

1. Extract the authenticated user_id.
2. Delete the image file from S3.
3. Delete the corresponding metadata from DynamoDB.
4. Return the deletion result.

Key Takeaways

• No rollback mechanism exists between S3 and DynamoDB.
• Consistent key structure is required for S3 objects.

GET /health

Overview

Checks the availability of dependent AWS services and reports the per-service status.

Prerequisites

• Permissions for:
  • S3 bucket access
  • DynamoDB table description

Implementation / Steps

1. Perform a health check on the S3 bucket.
2. Retrieve DynamoDB table status.
3. Mark services as healthy if available.
4. Return overall system status.

Key Takeaways

• The current implementation always returns "OK" if no exception occurs.
• Does not distinguish partial failures.
• Useful for monitoring and uptime checks.

Authentication Middleware

Overview

Validates incoming requests using JWT claims and attaches the user ID to the Lambda context.

Prerequisites

• API Gateway JWT authorizer configured
• JWT must include a sub claim

Implementation / Steps

1. Extract authorizer data from the request context.
2. Retrieve JWT claims.
3. Extract the sub field as the user ID.
4. Attach the user ID to the Lambda context.
5. Continue request processing.

Key Takeaways

• Supports multiple API Gateway authorizer formats.
• Fails immediately if authentication data is missing.
• Centralizes user identity handling.

Exception Handling Middleware

Overview

Handles all exceptions and converts them into consistent HTTP responses.

Prerequisites

• Custom exceptions must extend the base application exception

Implementation / Steps

1. Wrap the Lambda handler with middleware.
2. Catch known application exceptions.
3. Convert them into structured HTTP responses.
4. Catch unexpected errors and return a 500 response.

Key Takeaways

• Prevents unhandled runtime crashes.
• Ensures consistent error structure across endpoints.
• Separates error handling from business logic.