For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/modules/api.md (or send Accept: text/markdown).

API 모듈

버전 관리된 공개 계약, 키 배관, OpenAPI 표면.

이 가이드에 대해 질문하기

시작하기 전에

파일 → 폴더 열기를 사용하여 Visual Studio Code에서 다운로드한 supastack 프로젝트를 연 다음 터미널 → 새 터미널을 선택합니다. 저장소 루트는 package.json, 앱 및 패키지가 포함된 폴더입니다. 아래 명령을 실행하고 터미널을 열어 두십시오. 명령이 인식되지 않으면 계속하기 전에 도구 설치 가이드를 완료하세요.

먼저 플랫폼 튜토리얼을 읽어보세요. 서버는 브라우저 또는 전화 요청에 응답하는 앱 프로세스입니다. 웹은 apps/web/.env.local를 읽고, Expo는 apps/mobile/.env.local를 읽고, 데이터베이스 마이그레이션 명령은 루트 .env를 읽습니다. 데이터베이스 없는 /dashboard 데모는 Postgres를 마이그레이션해야 하는 실제 /auth 계정과 별개입니다. 전화 또는 데스크톱 전용 결제에는 별도로 실행되는 웹 백엔드가 필요합니다.

corepack pnpm --filter @supastack/web dev

설치 및 설정

packages/api는 공개 REST 표면의 진실 소스입니다: 요청, 응답, 오류 엔벌로프의 zod 스키마와 /api/v1/openapi에서 제공되는 OpenAPI 문서(openApiDocument). 라우트 핸들러는 형태를 재정의하는 대신 이 스키마들을 조합합니다.

API 키는 워크스페이스별로 sk_<env>_ 프리픽스로 발급되고, 상수 시간 비교로 해시되어 저장되며 스코프(기본 읽기)를 가집니다. api-keys.ts가 생성·조회·폐기를 소유합니다.

apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi

구현 워크플로

기존 버전 내에서 엔드포인트를 추가하세요: 스키마를 확장하고, 오류 엔벌로프를 유지하고, OpenAPI 표면을 재생성해 /api/docs가 정확하게 유지되게 합니다. 브레이킹 변경은 조용한 형태 변경이 아닌 새 버전을 얻습니다.

제시된 키에서 호출자의 워크스페이스를 해석하고, 웹 앱과 동일한 엔타이틀먼트·검증 규칙을 적용하고, 키별로 레이트 리밋합니다.

검증 및 문제 해결

각 라우트 형태를 패키지 스키마에 대해 계약 테스트합니다. 알 수 없는, 폐기된, 스코프 부족한 요청이 모두 문서화된 오류 엔벌로프로 실패하는지, OpenAPI 문서가 유효한 JSON으로 남는지 확인합니다.