Asset API Tutorial | Webflow API

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Create the POST endpoint

Import the APIRoute type from "astro" and create a POST endpoint that accepts the locals parameter. This endpoint will handle file uploads to the R2 bucket, including CORS preflight requests and form data processing.

Initialize API and handle CORS

Initialize the API utility with the origin set in your environment variables and handle CORS preflight requests. The OPTIONS method is used by browsers to check if the cross-origin request is allowed before sending the actual file data.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Key concepts:

CORS preflight: Browsers send OPTIONS requests to check cross-origin permissions
API initialization: Set up the API utility with the correct origin for CORS headers

Validate bucket configuration

Access the CLOUD_FILES binding and verify that the Object Storage bucket is properly configured. If the bucket isn't available, return a 500 error with a descriptive message to help with debugging.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Process form data and validate file

Extract the file from the FormData object and validate that it's a proper File instance.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Generate unique filename

Create a unique filename by combining a timestamp with the original filename. This prevents filename collisions and ensures each upload has a unique identifier. Extract the file extension to preserve the file type.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Upload file to the bucket

Use the .put() method to upload the file to the Object Storage bucket with the generated filename. Set the httpMetadata to include the file's content type, which is essential for proper file serving later.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Return success response

Return a success response with file details including the generated filename, Object Storage key, file size, and content type. This information is useful for the client to track the uploaded file.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};

Create the POST endpoint

Initialize API and handle CORS

Key concepts:

CORS preflight: Browsers send OPTIONS requests to check cross-origin permissions
API initialization: Set up the API utility with the correct origin for CORS headers

Validate bucket configuration

Access the CLOUD_FILES binding and verify that the Object Storage bucket is properly configured. If the bucket isn't available, return a 500 error with a descriptive message to help with debugging.

Process form data and validate file

Extract the file from the FormData object and validate that it's a proper File instance.

Generate unique filename

Upload file to the bucket

Return success response

Return a success response with file details including the generated filename, Object Storage key, file size, and content type. This information is useful for the client to track the uploaded file.

upload.ts

import type { APIRoute } from "astro";
import { API } from "../../utils/api";
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 formData = await request.formData();
    const file = formData.get("file");
    if (!file || !(file instanceof File)) {
    return API.error("Missing or invalid file", request, 400);
    }
    // Generate unique filename with timestamp
    const timestamp = Date.now();
    const extension = file.name.split(".").pop() || "";
    const filename = `${timestamp}-${file.name}`;
    // Upload to R2 bucket
    const object = await bucket.put(filename, file, {
    httpMetadata: {
        contentType: file.type,
    },
    });
    if (!object) {
    return API.error("Failed to upload file", request, 500);
    }
    return API.success(
    {
        success: true,
        filename,
        key: object.key,
        size: file.size,
        type: file.type,
    },
    request
    );
} catch (error) {
    console.error("Upload error:", error);
    return API.error("Upload failed", request, 500);
}
};