Asset API Tutorial | Webflow API

Create the POST Endpoint

The POST endpoint manages multipart uploads through two key operations: initializing new uploads and finalizing completed ones. The action query parameter determines which operation to perform.

Be sure to include the locals parameter in the POST endpoint to access your environment variables and CLOUD_FILES binding.

Setup CORS handling

Since multipart uploads require direct communication with the worker domain (not your Webflow Cloud domain), you need to set up proper CORS configuration. The imported API utility automatically handles CORS headers and preflight requests to ensure seamless cross-origin communication.

Access your Object Storage bucket

Retrieve the CLOUD_FILES binding that provides access to your Object Storage bucket. This binding contains all the multipart upload methods you'll need throughout the upload process.

Get Action Parameter

Parse the action query parameter to route between different multipart upload operations. The POST endpoint supports both create and complete actions.

Initialize multipart upload session

When action=create, this code establishes a new multipart upload session in Object Storage. The browser provides the key and contentType, then receives a unique uploadId that identifies the entire upload process.

Finalize multipart upload

Once all parts are uploaded through the PUT endpoint, the browser will send a request to this POST endpoint with the action parameter set to complete with an ordered list of all uploaded parts with their corresponding entity tags (ETags).

When action=complete, this endpoint consolidates all uploaded parts into a single file in Object Storage using multipartUpload.complete() method

multipart.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";

interface MultipartUploadRequest {
  key: string;
  contentType?: string;
}

interface CompleteMultipartRequest {
  uploadId: string;
  key: string;
  parts: R2UploadedPart[];
}

// Creates and completes a new multipart upload session
export const POST: APIRoute = async ({ request, locals }) => {
  // Set the origin for the API
  API.init(locals.runtime.env.ORIGIN);

  // Handle CORS preflight requests
  if (request.method === "OPTIONS") {
    console.log("CORS preflight request from:", request.headers.get("Origin"));
    return API.cors(request);
  }

  try {
    // Check if bucket is available
    const bucket = locals.runtime.env.CLOUD_FILES;
    if (!bucket) {
      return API.error("Cloud storage not configured", request, 500);
    }

    const url = new URL(request.url);
    const action = url.searchParams.get("action");

    if (!action) {
      return API.error("Missing action parameter", request, 400);
    }

    switch (action) {
      case "create": {
        // Create a new multipart upload
        const body: MultipartUploadRequest = await request.json();

        if (!body.key) {
          return API.error("Missing key parameter", request, 400);
        }

        try {
          const multipartUpload = await bucket.createMultipartUpload(body.key, {
            httpMetadata: body.contentType
              ? {
                  contentType: body.contentType,
                }
              : undefined,
          });

          return API.success(
            {
              success: true,
              key: multipartUpload.key,
              uploadId: multipartUpload.uploadId,
            },
            request
          );
        } catch (error) {
          console.error("Failed to create multipart upload:", error);
          return API.error("Failed to create multipart upload", request, 500);
        }
      }

      case "complete": {
        // Complete a multipart upload
        const body: CompleteMultipartRequest = await request.json();

        if (!body.uploadId || !body.key || !body.parts) {
          return API.error("Missing required parameters", request, 400);
        }

        try {
          const multipartUpload = bucket.resumeMultipartUpload(
            body.key,
            body.uploadId
          );

          // Parts are already in R2UploadedPart format
          const r2Parts = body.parts;

          const object = await multipartUpload.complete(r2Parts);

          return API.success(
            {
              success: true,
              key: object.key,
              etag: object.httpEtag,
              size: object.size,
            },
            request
          );
        } catch (error: any) {
          console.error("Failed to complete multipart upload:", error);
          return API.error(
            error.message || "Failed to complete multipart upload",
            request,
            400
          );
        }
      }

      default:
        return API.error(`Unknown action: ${action}`, request, 400);
    }
  } catch (error) {
    console.error("Multipart upload error:", error);
    return API.error("Multipart upload failed", request, 500);
  }
};

// Uploads individual parts of a multipart upload
export const PUT: APIRoute = async ({ request, locals }) => {
  // Set the origin for the API
  API.init(locals.runtime.env.ORIGIN);

  // Handle CORS preflight requests
  if (request.method === "OPTIONS") {
    console.log("CORS preflight request from:", request.headers.get("Origin"));
    return API.cors(request);
  }

  try {
    // Check if bucket is available
    const bucket = locals.runtime.env.CLOUD_FILES;
    if (!bucket) {
      return API.error("Cloud storage not configured", request, 500);
    }

    const url = new URL(request.url);
    const action = url.searchParams.get("action");

    if (action !== "upload-part") {
      return API.error(`Unknown action: ${action}`, request, 400);
    }

    const uploadId = url.searchParams.get("uploadId");
    const partNumberStr = url.searchParams.get("partNumber");
    const key = url.searchParams.get("key");

    if (!uploadId || !partNumberStr || !key) {
      return API.error("Missing uploadId, partNumber, or key", request, 400);
    }

    const partNumber = parseInt(partNumberStr);
    if (isNaN(partNumber) || partNumber < 1) {
      return API.error("Invalid part number", request, 400);
    }

    if (!request.body) {
      return API.error("Missing request body", request, 400);
    }

    try {
      const multipartUpload = bucket.resumeMultipartUpload(key, uploadId);

      // Convert request body to ArrayBuffer to get known length
      const arrayBuffer = await request.arrayBuffer();
      const uploadedPart = await multipartUpload.uploadPart(
        partNumber,
        arrayBuffer
      );

      return API.success(
        {
          success: true,
          partNumber: uploadedPart.partNumber,
          etag: uploadedPart.etag,
        },
        request
      );
    } catch (error: any) {
      console.error("Failed to upload part:", error);
      return API.error(error.message || "Failed to upload part", request, 400);
    }
  } catch (error) {
    console.error("Upload part error:", error);
    return API.error("Upload part failed", request, 500);
  }
};

// Aborts a multipart upload
export const DELETE: APIRoute = async ({ request, locals }) => {
  // Set the origin for the API
  API.init(locals.runtime.env.ORIGIN);

  // Handle CORS preflight requests
  if (request.method === "OPTIONS") {
    console.log("CORS preflight request from:", request.headers.get("Origin"));
    return API.cors(request);
  }

  try {
    // Check if bucket is available
    const bucket = locals.runtime.env.CLOUD_FILES;
    if (!bucket) {
      return API.error("Cloud storage not configured", request, 500);
    }

    const url = new URL(request.url);
    const action = url.searchParams.get("action");

    if (action !== "abort") {
      return API.error(`Unknown action: ${action}`, request, 400);
    }

    const uploadId = url.searchParams.get("uploadId");
    const key = url.searchParams.get("key");

    if (!uploadId || !key) {
      return API.error("Missing uploadId or key", request, 400);
    }

    try {
      const multipartUpload = bucket.resumeMultipartUpload(key, uploadId);
      await multipartUpload.abort();

      return API.success(
        {
          success: true,
          message: "Multipart upload aborted successfully",
        },
        request
      );
    } catch (error: any) {
      console.error("Failed to abort multipart upload:", error);
      return API.error(
        error.message || "Failed to abort multipart upload",
        request,
        400
      );
    }
  } catch (error) {
    console.error("Abort multipart upload error:", error);
    return API.error("Abort multipart upload failed", request, 500);
  }
};

export const OPTIONS: APIRoute = async ({ request, locals }) => {
  // Set the origin for the API
  API.init(locals.runtime.env.ORIGIN);
  return API.cors(request);
};