비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가
API를 이해하는 가장 쉬운 방법은 레스토랑에 비유하는 것입니다.
**API (Application Programming Interface)**는 두 시스템이 서로 대화하는 방법입니다.
| 실생활 예시 | API 역할 |
|---|---|
| 카카오톡에서 "프로필 보기" 클릭 | 서버에서 프로필 정보를 가져오는 API 호출 |
| 배달앱에서 "주문하기" 클릭 | 주문 정보를 서버에 저장하는 API 호출 |
| 인스타그램 피드 스크롤 | 새 게시물 목록을 가져오는 API 호출 |
bkamp 서비스에서 "쇼케이스 목록 보기"를 누르면:
1. 사용자가 앱 목록 페이지에 접속 2. 프론트엔드가 API 호출: GET /showcases/v1/showcases 3. 백엔드가 데이터베이스에서 앱 목록 조회 4. 백엔드가 JSON 형태로 응답 반환 5. 프론트엔드가 받은 데이터로 화면 구성
만약 레스토랑에서 메뉴판이 없다면 어떨까요?
API 개발도 마찬가지입니다. 약속(규약)이 없으면 혼란이 생깁니다.
❌ 약속이 없을 때 프론트엔드 개발자 A: "사용자 정보 어떻게 가져와요?" 백엔드 개발자 B: "GET /user 하면 돼요" 프론트엔드 개발자 C: "저는 GET /users/{id} 쓰던데요?" 백엔드 개발자 D: "아 그건 v2에서 바뀌었어요"
✅ 약속이 있을 때 문서: "사용자 정보 조회는 GET /users/v1/users/{id}를 사용합니다" 모든 개발자: "OK, 문서대로 하면 되겠네요"
모든 API 경로는 동일한 패턴을 따릅니다:
/{서비스}/{버전}/{리소스} 예시: GET /showcases/v1/showcases → 앱 목록 조회 GET /showcases/v1/showcases/123 → 앱 상세 조회 POST /showcases/v1/showcases → 앱 생성
모든 API 응답은 같은 구조를 사용합니다:
json{ "success": true, "data": { ... 실제 데이터 ... }, "error": null, "meta": { ... 추가 정보 (페이지네이션 등) ... } }
에러도 일관된 규칙을 따릅니다:
{서비스}_{도메인}_{에러유형} 예시: - AUTH_TOKEN_EXPIRED → 인증 토큰 만료 - SHOWCASE_NOT_FOUND → 앱을 찾을 수 없음 - RECIPE_STEP_REQUIRED → 레시피 스텝 필요
| 위치 | 규칙 | 예시 |
|---|---|---|
| JSON (프론트엔드 ↔ API) | camelCase | userId, createdAt |
| Python 코드 (백엔드) | snake_case | user_id, created_at |
| DB 컬럼 | snake_case | user_id, created_at |
┌────────────────────────────────────────────────────────────────┐ │ API 규약의 효과 │ ├────────────────────────────────────────────────────────────────┤ │ │ │ ✅ 예측 가능성 → 새 API도 기존 패턴으로 쉽게 예측 │ │ ✅ 생산성 향상 → "이건 어떻게 하죠?" 질문 감소 │ │ ✅ 유지보수 용이 → 누가 작성해도 일관된 코드 │ │ ✅ 협업 효율 → 프론트/백엔드 간 소통 비용 감소 │ │ ✅ 온보딩 단축 → 신규 개발자도 규칙만 알면 빠르게 적응 │ │ │ └────────────────────────────────────────────────────────────────┘
소프트웨어 개발에서 코드를 저장하는 방식은 크게 두 가지입니다:
| 방식 | 비유 | 특징 |
|---|---|---|
| 멀티레포 | 여러 건물에 나뉜 회사 | 팀별로 독립적, 소통 비용 높음 |
| 모노레포 | 한 건물에 모인 회사 | 빠른 소통, 공유 자원 활용 |
bkamp-portal/ ├── frontend/ # 프론트엔드 (Next.js) │ ├── apps/ │ │ ├── portal/ # 메인 포털 │ │ └── admin/ # 관리자 페이지 │ └── packages/ # 공유 패키지 │ ├── services/ # 백엔드 (FastAPI) │ ├── auth/ # 인증 서비스 │ ├── user/ # 사용자 서비스 │ ├── project/ # 쇼케이스 서비스 │ ├── recipe/ # 레시피 서비스 │ └── ... │ ├── shared/ # 백엔드 공통 모듈 │ ├── schemas/ # 공통 스키마 (API 규약!) │ ├── errors/ # 공통 에러 코드 │ └── utils/ # 공통 유틸리티 │ ├── infrastructure/ # 인프라 설정 └── docs/ # 문서
Claude Code와 같은 AI 개발 도구는 코드를 읽고 이해한 후 작업을 수행합니다.
┌────────────────────────────────────────────────────────────────┐ │ AI 개발 도구의 작업 흐름 │ ├────────────────────────────────────────────────────────────────┤ │ │ │ 1. 코드 읽기 (Read) → 기존 코드와 패턴 파악 │ │ 2. 컨텍스트 이해 → 프로젝트 구조와 규칙 이해 │ │ 3. 코드 작성 (Write) → 기존 패턴에 맞춰 새 코드 생성 │ │ 4. 일관성 유지 → 전체 프로젝트와 조화롭게 작성 │ │ │ └────────────────────────────────────────────────────────────────┘
❌ 멀티레포 환경에서의 AI "새 API를 만들어줘" → "음... 다른 API들은 어떻게 생겼죠? 다른 저장소를 봐야 하는데..." → 다른 서비스의 코드를 볼 수 없음 → 패턴을 파악하기 어려움
✅ 모노레포 환경에서의 AI "새 API를 만들어줘" → "기존 서비스들의 API 구조를 확인해볼게요" → GET /services/project/app/api/v1/endpoints/ → "아하, 이런 패턴으로 작성하면 되겠군요!" → 일관된 코드 생성
python# shared/ 폴더의 공통 모듈을 AI가 바로 찾아서 사용 # AI: "아, 이미 에러 코드가 정의되어 있네요. 그대로 사용할게요." from shared.errors.codes import ErrorCode from shared.schemas.response import CamelCaseModel
bkamp-portal/ ├── docs/ │ └── 01-development/ │ └── 06_API_규약_설계서.md ← AI가 규약 문서 참조 │ ├── services/ │ └── project/ │ └── app/api/v1/ ← 규약을 따르는 실제 코드 참조
AI가 문서와 실제 코드를 동시에 참조할 수 있어, 규약에 맞는 코드를 정확하게 생성합니다.
1. "레시피 서비스 API 만들어줘" 2. AI: "다른 서비스 코드를 볼 수 없어서, 일반적인 방식으로 만들게요" 3. 결과: 기존 서비스와 다른 스타일의 API 생성 4. 개발자가 수동으로 일관성 맞춤 (시간 소모)
1. "레시피 서비스 API 만들어줘" 2. AI: "기존 project 서비스 구조를 참고할게요" - services/project/app/api/v1/endpoints/ 확인 - shared/schemas/response.py 확인 - docs/01-development/06_API_규약_설계서.md 확인 3. 결과: 기존 서비스와 동일한 스타일의 API 생성 4. 바로 사용 가능! (시간 절약)
| 개념 | 한 줄 설명 | 중요한 이유 |
|---|---|---|
| API | 시스템 간 대화 방법 | 프론트-백엔드 연결의 핵심 |
| API 규약 | API를 만드는 약속 | 일관성, 예측 가능성, 협업 효율 |
| 모노레포 | 하나의 저장소에 모든 코드 | AI가 전체 맥락 파악 가능 |
| 시너지 | 규약 + 모노레포 + AI | 빠르고 일관된 개발 가능 |
"API 규약이 있는 모노레포에서 AI 도구를 사용하면, AI가 기존 코드 패턴을 학습하여 일관된 코드를 자동으로 생성한다. 이것이 bkamp가 빠르게 개발될 수 있었던 핵심 비결이다."
문서 버전: 1.0 작성일: 2025-12-26 참고 문서: API 규약 설계서
댓글을 작성하려면 로그인이 필요합니다.
비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가
API를 이해하는 가장 쉬운 방법은 레스토랑에 비유하는 것입니다.
**API (Application Programming Interface)**는 두 시스템이 서로 대화하는 방법입니다.
| 실생활 예시 | API 역할 |
|---|---|
| 카카오톡에서 "프로필 보기" 클릭 | 서버에서 프로필 정보를 가져오는 API 호출 |
| 배달앱에서 "주문하기" 클릭 | 주문 정보를 서버에 저장하는 API 호출 |
| 인스타그램 피드 스크롤 | 새 게시물 목록을 가져오는 API 호출 |
bkamp 서비스에서 "쇼케이스 목록 보기"를 누르면:
1. 사용자가 앱 목록 페이지에 접속 2. 프론트엔드가 API 호출: GET /showcases/v1/showcases 3. 백엔드가 데이터베이스에서 앱 목록 조회 4. 백엔드가 JSON 형태로 응답 반환 5. 프론트엔드가 받은 데이터로 화면 구성
만약 레스토랑에서 메뉴판이 없다면 어떨까요?
API 개발도 마찬가지입니다. 약속(규약)이 없으면 혼란이 생깁니다.
❌ 약속이 없을 때 프론트엔드 개발자 A: "사용자 정보 어떻게 가져와요?" 백엔드 개발자 B: "GET /user 하면 돼요" 프론트엔드 개발자 C: "저는 GET /users/{id} 쓰던데요?" 백엔드 개발자 D: "아 그건 v2에서 바뀌었어요"
✅ 약속이 있을 때 문서: "사용자 정보 조회는 GET /users/v1/users/{id}를 사용합니다" 모든 개발자: "OK, 문서대로 하면 되겠네요"
모든 API 경로는 동일한 패턴을 따릅니다:
/{서비스}/{버전}/{리소스} 예시: GET /showcases/v1/showcases → 앱 목록 조회 GET /showcases/v1/showcases/123 → 앱 상세 조회 POST /showcases/v1/showcases → 앱 생성
모든 API 응답은 같은 구조를 사용합니다:
json{ "success": true, "data": { ... 실제 데이터 ... }, "error": null, "meta": { ... 추가 정보 (페이지네이션 등) ... } }
에러도 일관된 규칙을 따릅니다:
{서비스}_{도메인}_{에러유형} 예시: - AUTH_TOKEN_EXPIRED → 인증 토큰 만료 - SHOWCASE_NOT_FOUND → 앱을 찾을 수 없음 - RECIPE_STEP_REQUIRED → 레시피 스텝 필요
| 위치 | 규칙 | 예시 |
|---|---|---|
| JSON (프론트엔드 ↔ API) | camelCase | userId, createdAt |
| Python 코드 (백엔드) | snake_case | user_id, created_at |
| DB 컬럼 | snake_case | user_id, created_at |
┌────────────────────────────────────────────────────────────────┐ │ API 규약의 효과 │ ├────────────────────────────────────────────────────────────────┤ │ │ │ ✅ 예측 가능성 → 새 API도 기존 패턴으로 쉽게 예측 │ │ ✅ 생산성 향상 → "이건 어떻게 하죠?" 질문 감소 │ │ ✅ 유지보수 용이 → 누가 작성해도 일관된 코드 │ │ ✅ 협업 효율 → 프론트/백엔드 간 소통 비용 감소 │ │ ✅ 온보딩 단축 → 신규 개발자도 규칙만 알면 빠르게 적응 │ │ │ └────────────────────────────────────────────────────────────────┘
소프트웨어 개발에서 코드를 저장하는 방식은 크게 두 가지입니다:
| 방식 | 비유 | 특징 |
|---|---|---|
| 멀티레포 | 여러 건물에 나뉜 회사 | 팀별로 독립적, 소통 비용 높음 |
| 모노레포 | 한 건물에 모인 회사 | 빠른 소통, 공유 자원 활용 |
bkamp-portal/ ├── frontend/ # 프론트엔드 (Next.js) │ ├── apps/ │ │ ├── portal/ # 메인 포털 │ │ └── admin/ # 관리자 페이지 │ └── packages/ # 공유 패키지 │ ├── services/ # 백엔드 (FastAPI) │ ├── auth/ # 인증 서비스 │ ├── user/ # 사용자 서비스 │ ├── project/ # 쇼케이스 서비스 │ ├── recipe/ # 레시피 서비스 │ └── ... │ ├── shared/ # 백엔드 공통 모듈 │ ├── schemas/ # 공통 스키마 (API 규약!) │ ├── errors/ # 공통 에러 코드 │ └── utils/ # 공통 유틸리티 │ ├── infrastructure/ # 인프라 설정 └── docs/ # 문서
Claude Code와 같은 AI 개발 도구는 코드를 읽고 이해한 후 작업을 수행합니다.
┌────────────────────────────────────────────────────────────────┐ │ AI 개발 도구의 작업 흐름 │ ├────────────────────────────────────────────────────────────────┤ │ │ │ 1. 코드 읽기 (Read) → 기존 코드와 패턴 파악 │ │ 2. 컨텍스트 이해 → 프로젝트 구조와 규칙 이해 │ │ 3. 코드 작성 (Write) → 기존 패턴에 맞춰 새 코드 생성 │ │ 4. 일관성 유지 → 전체 프로젝트와 조화롭게 작성 │ │ │ └────────────────────────────────────────────────────────────────┘
❌ 멀티레포 환경에서의 AI "새 API를 만들어줘" → "음... 다른 API들은 어떻게 생겼죠? 다른 저장소를 봐야 하는데..." → 다른 서비스의 코드를 볼 수 없음 → 패턴을 파악하기 어려움
✅ 모노레포 환경에서의 AI "새 API를 만들어줘" → "기존 서비스들의 API 구조를 확인해볼게요" → GET /services/project/app/api/v1/endpoints/ → "아하, 이런 패턴으로 작성하면 되겠군요!" → 일관된 코드 생성
python# shared/ 폴더의 공통 모듈을 AI가 바로 찾아서 사용 # AI: "아, 이미 에러 코드가 정의되어 있네요. 그대로 사용할게요." from shared.errors.codes import ErrorCode from shared.schemas.response import CamelCaseModel
bkamp-portal/ ├── docs/ │ └── 01-development/ │ └── 06_API_규약_설계서.md ← AI가 규약 문서 참조 │ ├── services/ │ └── project/ │ └── app/api/v1/ ← 규약을 따르는 실제 코드 참조
AI가 문서와 실제 코드를 동시에 참조할 수 있어, 규약에 맞는 코드를 정확하게 생성합니다.
1. "레시피 서비스 API 만들어줘" 2. AI: "다른 서비스 코드를 볼 수 없어서, 일반적인 방식으로 만들게요" 3. 결과: 기존 서비스와 다른 스타일의 API 생성 4. 개발자가 수동으로 일관성 맞춤 (시간 소모)
1. "레시피 서비스 API 만들어줘" 2. AI: "기존 project 서비스 구조를 참고할게요" - services/project/app/api/v1/endpoints/ 확인 - shared/schemas/response.py 확인 - docs/01-development/06_API_규약_설계서.md 확인 3. 결과: 기존 서비스와 동일한 스타일의 API 생성 4. 바로 사용 가능! (시간 절약)
| 개념 | 한 줄 설명 | 중요한 이유 |
|---|---|---|
| API | 시스템 간 대화 방법 | 프론트-백엔드 연결의 핵심 |
| API 규약 | API를 만드는 약속 | 일관성, 예측 가능성, 협업 효율 |
| 모노레포 | 하나의 저장소에 모든 코드 | AI가 전체 맥락 파악 가능 |
| 시너지 | 규약 + 모노레포 + AI | 빠르고 일관된 개발 가능 |
"API 규약이 있는 모노레포에서 AI 도구를 사용하면, AI가 기존 코드 패턴을 학습하여 일관된 코드를 자동으로 생성한다. 이것이 bkamp가 빠르게 개발될 수 있었던 핵심 비결이다."
문서 버전: 1.0 작성일: 2025-12-26 참고 문서: API 규약 설계서
댓글을 작성하려면 로그인이 필요합니다.