Call your own API

내 백엔드 API를 토큰이 자동으로 붙는 클라이언트로 호출합니다.

내 서비스의 백엔드 API를 호출할 때는 킷의 api 클라이언트를 그대로 씁니다. 로그인 토큰이 자동으로 붙고, 토큰이 만료되면 알아서 갱신한 뒤 다시 시도합니다.

What the client does

모든 요청에 Authorization: Bearer ...를 자동으로 붙입니다.
401이 오면 리프레시 쿠키로 토큰을 한 번 갱신하고 요청을 재시도합니다.
갱신에도 실패하면 로그아웃 상태가 되어 로그인 안내가 나옵니다.
주소는 /api 아래로 나가고, Next.js 프록시가 백엔드로 전달합니다.

1. Write the API function

src/app/(service)/reports/
├── api.ts            서버 호출 함수
├── queries.ts        TanStack Query 훅
└── ReportsPage.tsx

app/(service)/reports/api.ts

import { api } from "@/meerkit";

export interface Report {
  id: number;
  title: string;
}

export const reportsApi = {
  list: () => api.get<Report[]>("/reports").then((r) => r.data),
  create: (title: string) => api.post<Report>("/reports", { title }).then((r) => r.data),
};

2. Wrap it in a hook

서버 데이터는 TanStack Query에 맡깁니다. 쿼리 키는 ["meerkit", ...]와 겹치지 않게 서비스 이름으로 시작하세요.

queries.ts

import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { reportsApi } from "./api";

const key = ["reports"] as const;

export const useReports = () => useQuery({ queryKey: key, queryFn: reportsApi.list });

export function useCreateReport() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: reportsApi.create,
    onSuccess: () => queryClient.invalidateQueries({ queryKey: key }),
  });
}

3. Use it in the screen

ReportsPage.tsx

"use client";

import { RequireAuth } from "@/meerkit";
import { useReports } from "./queries";

function List() {
  const { data, isLoading, isError } = useReports();
  if (isLoading) return <p>불러오는 중…</p>;
  if (isError) return <p>목록을 불러오지 못했습니다.</p>;
  return <ul>{data?.map((r) => <li key={r.id}>{r.title}</li>)}</ul>;
}

export const ReportsPage = () => (
  <RequireAuth>
    <List />
  </RequireAuth>
);

Handling errors

Status	의미	권장 처리
400 / 422	입력값 오류	서버가 준 detail을 폼 아래에 표시
401	로그인 필요 (갱신도 실패)	클라이언트가 이미 처리. 화면은 RequireAuth가 안내
403	역할이 허용되지 않음	접근 권한 없음 안내
404	대상 없음	빈 상태 또는 안내 표시
5xx	서버 오류	재시도 안내

오류 메시지 꺼내기

tsx

import { isAxiosError } from "axios";

function message(error: unknown) {
  if (isAxiosError(error)) return error.response?.data?.detail ?? "요청에 실패했습니다.";
  return "알 수 없는 오류가 발생했습니다.";
}

axios를 직접 만들어 쓰면 토큰이 붙지 않습니다. 서비스 API는 항상 킷의 api를 사용하세요.