Developing Web API

웹 API 개발

서버 구조

packages/server/src/
├── index.ts              # 서버 진입점 (localhost:3000), 미들웨어, 인증
├── history-sync.ts       # 히스토리 동기화 진입점
├── history/
│   ├── store.ts          # 분할 히스토리 SQLite 저장소
│   ├── store.test.ts     # store 단위 테스트
│   ├── sync.ts           # 히스토리 동기화 로직
│   └── types.ts          # 히스토리 타입 정의
├── lib/
│   └── resolve-model.ts  # provider+model 유효성 검증 및 해석
└── routes/
    ├── decks.ts          # 덱 관련
    ├── cards.ts          # 카드 관련
    ├── split.ts          # 분할 (preview/apply/reject)
    ├── backup.ts         # 백업/롤백
    ├── media.ts          # Anki 미디어 프록시
    ├── clinic.ts         # 검증 5종 + YAGNI + fix/apply
    ├── llm.ts            # LLM 모델/프로바이더 정보
    ├── embedding.ts      # 임베딩
    ├── prompts.ts        # 프롬프트 버전 관리 + systemPrompt CAS
    └── history.ts        # 분할 히스토리

API 인증 미들웨어

모든 /api/* 요청은 인증 미들웨어를 거친다. /api/health만 면제.

인증 방식 (2가지)

1. X-API-Key 헤더: X-API-Key: <key>
2. Bearer 토큰: Authorization: Bearer <key>

둘 다 전달되면 X-API-Key가 우선. timing-safe 비교로 타이밍 공격 방지.

환경변수

• REQUIRE_API_KEY=true + API_KEY 미설정 -> 모든 API 503 반환 (/api/health 제외)
• REQUIRE_API_KEY=false -> 인증 비활성화 (Tailscale 등 격리 환경 전용)

CORS

CORS_ORIGINS 환경변수로 허용 origin 제어. 기본: http://localhost:5173, http://127.0.0.1:5173. 쉼표 구분. 허용 헤더: Content-Type, X-API-Key, Authorization.

전체 엔드포인트 목록

Health

Decks & Cards

Split & Backup

Clinic

Embedding

LLM

History

Media

Prompts -- managing-prompts 스킬 참조

라우트 추가 패턴

라우트 파일은 prefix 없이 상대 경로로 정의하고, index.ts에서 prefix를 부여하는 패턴을 사용한다.

// packages/server/src/routes/new-route.ts
// 라우트 내부에서는 prefix 없이 정의
import { NotFoundError, ValidationError } from "@anki-splitter/core";
import { Hono } from "hono";

const app = new Hono();

app.get("/:id", async (c) => {
  const id = c.req.param("id");
  const resource = await findResource(id);
  if (!resource) throw new NotFoundError(`리소스 ${id}를 찾을 수 없습니다`);
  return c.json(resource);
});

export default app;

// packages/server/src/index.ts에서 prefix 부여하여 등록
import newRoute from './routes/new-route.js';
app.route('/api/new-route', newRoute);
// -> GET /api/new-route/:id 로 접근 가능

주의사항

• 카드 목록 API에서 텍스트 200자 제한 (성능) -> 상세 조회 별도 필요
• c.json(result) 형식으로 응답 반환
• 에러는 throw -> 글로벌 app.onError 핸들러가 중앙 처리 (try/catch 불필요)
• PUT /api/prompts/versions/:id에서 systemPrompt 필드 수정 차단 -> /api/prompts/system 전용

디버깅

# 헬스 체크 (인증 불필요)
curl -s http://localhost:3000/api/health | python3 -m json.tool

# 인증이 필요한 엔드포인트
curl -s -H "X-API-Key: $ANKI_SPLITTER_API_KEY" http://localhost:3000/api/decks | python3 -m json.tool
curl -s -H "Authorization: Bearer $ANKI_SPLITTER_API_KEY" http://localhost:3000/api/cards/1757399484677 | python3 -m json.tool

상세 참조

• references/route-patterns.md -- 전체 라우트 패턴, 요청/응답 예시
• references/error-handling.md -- Hono 에러 핸들러, 에러 클래스
• references/troubleshooting.md -- API 디버깅 팁, 인증 문제 해결