Overview

Kommunity uses Amazon S3 for storing images with presigned URLs to securely handle direct browser-to-S3 uploads. This document explains how the image upload flow works and how to implement it in your applications.

How It Works

The image upload process involves three main steps:

Generate Presigned URL: Request a presigned S3 URL from our API
Upload to S3: Upload the image directly to S3 using the presigned URL
Get CDN URL: Store the resulting CDN URL for future use

API Endpoint

To get a presigned URL, make a POST request to our upload URL endpoint:

POST /api/v1/images/upload-url
Header: x-kommunity-api-key: YOUR_API_KEY

Response

{
  "success": true,
  "upload_url": "https://s3-bucket-url.amazonaws.com/uuid?presigned-params",
  "image_url": "https://cdn.kommunity.app/uuid"
}

upload_url: Use this URL to upload your file via PUT request
image_url: The CDN URL where your image will be accessible after upload

Client Implementation

Here's how to implement the upload process:

Get the presigned URL

First, request a presigned URL from the API:

const getUploadUrl = async () => {
  const response = await fetch("/api/v1/images/upload-url", {
    method: "POST",
    headers: {
      "x-kommunity-api-key": "YOUR_API_KEY",
    },
  });

  return await response.json();
};

Upload the image to S3

Next, use the presigned URL to upload the image directly to S3:

const uploadImage = async (file) => {
  // Get the presigned URL
  const { upload_url, image_url } = await getUploadUrl();

  // Upload directly to S3
  const uploadResponse = await fetch(upload_url, {
    method: "PUT",
    body: file,
    headers: {
      "Content-Type": file.type,
    },
  });

  if (!uploadResponse.ok) {
    throw new Error("Upload failed");
  }

  // Return the CDN URL
  return image_url;
};

Use the uploaded image

Finally, use the returned CDN URL in your application:

const handleImageUpload = async (event) => {
  const file = event.target.files[0];
  if (!file) return;
  
  try {
    const imageUrl = await uploadImage(file);
    
    // Save the URL to your state or form data
    setFormData((prev) => ({
      ...prev,
      eventImage: imageUrl
    }));
    
    // Example: Update UI to show the uploaded image
    setImagePreview(imageUrl);
  } catch (error) {
    console.error("Image upload failed:", error);
    // Handle the error appropriately
  }
};

This URL is now permanently accessible and can be stored in your database with event details.

Image Upload Process