This is a beta course, so its structure, chapters, and examples may continue to change.

Server-side API Calls in Astro

Astro can do API/SSR, but keep “static first, minimal runtime”. Only put what must run at runtime on the server.

API routes

Place under src/pages/api/*.ts (or .js), export GET/POST handlers.
Return a Response object; you can use the json() helper.
Edge/Node runtimes depend on hosting; avoid Node-only modules if targeting Edge.

// src/pages/api/hello.ts
export async function GET() {
  return new Response(JSON.stringify({ msg: "hello" }), {
    headers: { "Content-Type": "application/json" },
  });
}

SSR pages

Export prerender = false in the page to enable SSR.
Use Astro.request for headers/query, and fetch your backend.
Good for user-context data, real-time, personalization; keep static when possible.

Middle-tier purposes

Wrap backend APIs: auth, rate-limit, signing—protect upstream.
Edge rendering: return personalized content close to users.
Progressive dynamic: list static, detail or user bits via API.

Deployment notes

For Cloudflare Pages Functions/Workers, stick to Fetch API; avoid Node-specific modules.
Configure routing so /api/* is not shadowed by static assets.

Pain points of traditional FE/BE split

Calling third-party APIs in a classic split setup often hits:

CORS limits: browser same-origin blocks direct calls
Security: API keys may leak in frontend bundles
Complexity: need a separate backend to proxy

Example with Laravel + Vue.js:

// Laravel backend
public function getIpInfo(Request $request) {
    $response = Http::get('http://ip-api.com/json/');
    return response()->json($response->json());
}

// Vue.js frontend
async function fetchIpInfo() {
    const response = await fetch('/api/ip-info');
    const data = await response.json();
    this.ipInfo = data;
}

🌐浏览器

↓ API 请求

🖥️后端服务

↓ 转发请求

🔌第三方 API

↑ 返回数据

🖥️后端服务

↑ 返回数据

🌐浏览器

Astro’s elegant solution

Astro gives a full-stack path: frontend UI + backend API together.

// src/pages/api/ip-info.ts
import type { APIRoute } from 'astro';

interface IpInfo {
    query: string;
    country: string;
    city: string;
    isp: string;
    regionName: string;
}

export const GET: APIRoute = async () => {
    try {
        const response = await fetch('<http://ip-api.com/json/>');
        if (!response.ok) {
            return new Response(
                JSON.stringify({ error: 'Failed to fetch IP info' }),
                {
                    status: 500,
                    headers: { 'Content-Type': 'application/json' }
                }
            );
        }

        const data: IpInfo = await response.json();
        return new Response(
            JSON.stringify(data),
            {
                status: 200,
                headers: { 'Content-Type': 'application/json' }
            }
        );
    } catch (e) {
        return new Response(
            JSON.stringify({ error: e instanceof Error ? e.message : 'Unknown error' }),
            {
                status: 500,
                headers: { 'Content-Type': 'application/json' }
            }
        );
    }
};

<!-- src/components/IpInfoDemo.vue -->
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { VueAlert, VueButton, VueCard, VueFlex, VueGrid, VueText } from '@kuaiyizhi/kit-ui-vue';

interface IpInfo {
    query: string;
    country: string;
    city: string;
    isp: string;
    regionName: string;
}

const ipInfo = ref<IpInfo | null>(null);
const error = ref<string | null>(null);
const loading = ref(false);

const fetchIpInfo = async () => {
    loading.value = true;
    error.value = null;
    try {
        const response = await fetch('/api/ip-info');
        if (!response.ok) {
            const errorData = await response.json();
            throw new Error(errorData.error || 'Failed to fetch IP info');
        }
        ipInfo.value = await response.json();
    } catch (e) {
        error.value = e instanceof Error ? e.message : 'Unknown error';
    } finally {
        loading.value = false;
    }
};

onMounted(fetchIpInfo);
</script>

<template>
    <VueCard surface="base" shadow="soft" padding="default" not-content>
        <VueFlex align="center" justify="between">
            <VueText as="h3" size="xl" weight="semibold">IP Info</VueText>
            <VueButton :disabled="loading" @click="fetchIpInfo">
                {{ loading ? 'Loading...' : 'Refresh' }}
            </VueButton>
        </VueFlex>

        <VueAlert v-if="error" tone="error">{{ error }}</VueAlert>

        <VueGrid v-if="ipInfo" base-columns="1" columns="2" gap="md">
            <VueCard surface="muted" shadow="none" padding="compact">
                <VueText as="div" size="sm" tone="muted">IP Address</VueText>
                <VueText as="div" size="lg">{{ ipInfo.query }}</VueText>
            </VueCard>
            <!-- more fields ... -->
        </VueGrid>
    </VueCard>
</template>

Now a concrete demo:

Flow

Frontend component calls internal /api/ip-info
Astro API route requests external IP service
API route returns the result
Frontend updates UI

Benefits:

Secrets and sensitive steps stay server-side
No extra backend service—simpler deploy
Full typing support for better DX
Unified error/loading handling

Advantages recap

Simpler code: no separate backend API needed
Developer efficiency: full-stack in one file
Security: API calls server-side, keys stay hidden
Performance: supports static and incremental generation

Best practices

Cache smartly: build-time fetch for rarely changing data
Error handling: add proper error/loading states
Type safety: define response types with TypeScript

---
interface IpInfo {
  query: string;
  country: string;
  city: string;
  isp: string;
}

try {
  const response = await fetch('<http://ip-api.com/json/>');
  const ipInfo: IpInfo = await response.json();
} catch (error) {
  console.error('Failed to fetch IP info:', error);
}
---

Conclusion

With server components and API routes, Astro neatly solves API-call pain points in traditional FE/BE splits. You can ship full-stack features with concise code while keeping security and performance in check—better developer velocity, better user experience.

Documentation Site Deployment & Optimization

Learn how to deploy and optimize an Astro documentation site

Data and Content Management

Master Astro’s data fetching and content handling