APIFuse에서 생성된 스키마 아티팩트를 서버 사이드 Next.js App Router 코드에서 사용하는 방법입니다.

Next.js App Router 연동

개발자 MCP로 operation을 탐색하고 생성된 TypeScript·Zod 아티팩트를 가져온 뒤, 서버 사이드 App Router 코드에서 APIFuse를 호출합니다. 클라이언트 컴포넌트에서 시크릿 키로 APIFuse를 직접 호출하지 마세요.

서버 전용 원칙

APIFuse API 키와 조직 인증 정보는 서버 전용 코드에 보관하세요. 브라우저 컴포넌트에는 애플리케이션 고유의 DTO만 전달하고, provider 자격 증명이나 connection 참조는 노출하지 마세요.

1. 개발자 MCP로 아티팩트 가져오기

코딩 에이전트에게 다음을 요청하세요.

apifuse_dev_search_operations로 operation을 검색합니다.
apifuse_dev_get_operation_spec으로 operation 계약을 가져옵니다.
apifuse_dev_get_schema_bundle로 TypeScript·Zod 대상 아티팩트를 가져옵니다.

생성된 아티팩트는 서버 전용 모듈에 커밋합니다. 예: src/server/apifuse/generated/weather.ts

2. 서버 라우트 만들기

// app/api/weather/route.ts
import { NextResponse } from "next/server";
import {
  ShortForecastInputSchema,
  ShortForecastOutputSchema,
} from "@/server/apifuse/generated/weather";

export async function POST(request: Request) {
  const input = ShortForecastInputSchema.parse(await request.json());

  const response = await fetch(
    "https://api.apifuse.com/v1/korea-weather/short-forecast",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.APIFUSE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(input),
      cache: "no-store",
    },
  );

  if (!response.ok) {
    return NextResponse.json(
      { error: "apifuse_request_failed" },
      { status: response.status },
    );
  }

  const parsed = ShortForecastOutputSchema.parse(await response.json());
  return NextResponse.json({ forecast: parsed });
}

3. 클라이언트 컴포넌트에서 호출하기

"use client";

export async function loadForecast() {
  const response = await fetch("/api/weather", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ baseDate: "20260525", baseTime: "0500", gridX: 60, gridY: 127 }),
  });

  if (!response.ok) throw new Error("Forecast request failed");
  return response.json();
}

안전 체크리스트

서버 경계에서 생성된 Zod 스키마를 사용하세요.
APIFUSE_API_KEY는 서버 환경 변수에 보관하세요.
provider 자격 증명, 조직 인증 정보, connection 식별자를 브라우저에 노출하지 마세요.
apifuse_dev_* 도구는 탐색·스키마·가이드 용도이며, provider operation은 서버 사이드 게이트웨이 호출로 실행합니다.
bundleHash 또는 targetArtifactHash 값이 변경되면 애플리케이션 코드를 재생성하고 검토하세요.