04. 나만의 API 만들기 (API Provider)

"소비자(Consumer)에서 생산자(Provider)로." 남의 데이터를 받아먹는 것에 만족하지 마세요. 이제 여러분의 컴퓨터를 전 세계에 데이터를 제공하는 본부(Server)로 변신시킬 차례입니다.

1. Server: 24시간 깨어있는 편의점

우리가 지금까지 짠 파이썬 코드는 실행 버튼을 누르면 print() 하고 바로 꺼졌습니다. 하지만 서버는 다릅니다.

일반 프로그램: "할 일 다 했으니 퇴근합니다." (종료 - Exit)
서버 프로그램: "손님이 올 때까지 무한 대기합니다." (무한 루프 - Loop)

여러분의 컴퓨터에 FastAPI라는 프로그램을 깔면, 컴퓨터는 잠들지 않고 인터넷 세상의 요청(Request)을 기다리는 '디지털 편의점'이 됩니다.

2. Why FastAPI? (파이썬의 혁명)

옛날에는 서버를 만들려면 Django, Flask 같은 무겁고 어려운 도구를 썼습니다. 하지만 지금은 FastAPI의 시대입니다.

특징	설명	비유
속도	Node.js, Go와 맞먹을 정도로 엄청나게 빠릅니다.	스포츠카 🏎️
생산성	코드 양이 기존 대비 40% 줄어듭니다.	밀키트 🥘 (재료 손질 끝)
자동 문서화	API 사용 설명서(Swagger)를 알아서 만들어줍니다.	자동 메뉴판 📜 (핵심!)

3. Hello World: 3초 만에 가게 오픈하기

백문이 불여일타. 바로 서버를 띄워봅시다.

Step 1. 프로젝트 준비 (Project Setup)

깨끗한 작업 환경을 위해 전용 폴더와 가상환경을 먼저 만듭니다.

폴더 생성 및 열기: VS Code에서 fastapi-hello라는 새 폴더를 만들고 엽니다 (Open Folder).
터미널 열기: 상단 메뉴 Terminal -> New Terminal을 클릭합니다.
가상환경 생성 및 활성화: VS Code의 명령 팔레트를 사용하면 가장 쉽습니다.
- 맥: Cmd + Shift + P / 윈도우: Ctrl + Shift + P
- 입력창에 Python: Create Environment 입력 후 엔터
- Venv 선택 → 현재 Python 버전 선택
- (잠시 후 우측 하단에 ('.venv': venv)라고 뜨면 격리된 방 생성 완료!)
라이브러리 설치: 이제 격리된 방에 도구들을 설치합니다.
```
pip install fastapi uvicorn
```
fastapi: 서버를 만드는 도구 (레시피)
uvicorn: 서버를 실행하는 엔진 (점장님)

Step 2. 코드 작성 (`main.py`)

VS Code에서 main.py 파일을 만들고 붙여넣으세요.

from fastapi import FastAPI

app = FastAPI() # 1. 가게 간판 달기

@app.get("/") # 2. 경로(Path) 설정: 정문으로 들어오면
def read_root():
    return {"message": "Hello World"} # 3. JSON 응답 (자동 변환!)

Step 3. 서버 실행 (Run)

터미널에 다음 명령어를 입력합니다.

uvicorn main:app --reload

main: 파일 이름 (main.py)
app: 우리가 만든 app 객체
--reload: 코드를 고치면 알아서 재시작해줘 (개발 꿀템)

👉 결과 확인: 브라우저를 켜고 http://127.0.0.1:8000에 접속해보세요. 화면에 {"message": "Hello World"}가 떴다면 성공입니다! 여러분의 컴퓨터가 웹 서버가 된 것입니다.

4. The Magic: 자동 메뉴판 (Swagger UI) ✨

FastAPI의 가장 강력한 무기입니다. 개발자가 제일 싫어하는 게 "문서 작성"인데, 이걸 자동으로 해줍니다.

브라우저 주소 뒤에 /docs를 붙여보세요.
http://127.0.0.1:8000/docs

짜잔! 여러분이 만든 API를 테스트할 수 있는 대화형 웹사이트가 자동으로 생성되었습니다. 프론트엔드 개발자에게 "이거 보고 개발하세요"라고 링크만 던져주면 끝입니다.

5. Parameter 1: 경로 변수 (Path Parameter)

손님이 "그냥 밥 주세요"가 아니라 "3번 메뉴 주세요"라고 할 수 있어야겠죠? URL 경로 중간에 구멍(변수)을 뚫는 방식입니다.

@app.get("/items/{item_id}") # 구멍 뚫기 {}
def read_item(item_id: int): # 변수로 받기
    return {"item_id": item_id, "name": "명품 시계"}

테스트: http://127.0.0.1:8000/items/5 로 접속
원리: URL에 적힌 숫자 5가 파이썬 함수의 item_id로 쏙 들어갑니다.

6. Parameter 2: 옵션 변수 (Query Parameter)

이번에는 검색창처럼 옵션을 받는 방식입니다. ? 뒤에 붙는 값을 처리해봅시다.

실습: '나의 OOTD(Outfit Of The Day)' API 👗

요일(day)을 입력하면 내가 그날 입었던 옷을 알려주는 서버입니다. 나중에 "지난주 월요일에 뭐 입었지?" 하고 찾아볼 때 씁니다.

1단계: 데이터 준비 (내 옷장 기록)

ootd_log = {
    "monday": "검정 슬랙스에 흰 셔츠",
    "tuesday": "청바지에 후드티",
    "wednesday": "트레이닝복 세트",
    "thursday": "베이지색 트렌치코트",
    "friday": "화려한 파티룩"
}

2단계: API 로직 작성

@app.get("/ootd")
def get_ootd(day: str): # URL에서는 ?day=... 로 받음
    outfit = ootd_log.get(day, "기록된 코디가 없습니다.")
    return {"day": day, "outfit": outfit}

3단계: 테스트

브라우저 주소창에 바로 입력해 봅시다.
http://127.0.0.1:8000/ootd?day=friday
결과: {"day": "friday", "outfit": "화려한 파티룩"}

React(프론트, 5173번 포트)와 FastAPI(백엔드, 8000번 포트)를 연결하려고 하면 빨간 에러(CORS Error)가 뜹니다. CORS(Cross-Origin Resource Sharing)는 브라우저가 보안상 "출신(Port)이 다른 사이트끼리의 대화"를 기본적으로 차단하는 규칙입니다.

서버 코드의 app = FastAPI() 바로 아랫줄에 이 '통행증 발급 코드'를 꼭 붙여넣어 주세요. (국룰 설정)

from fastapi.middleware.cors import CORSMiddleware

# app = FastAPI()  <-- 이 줄 뒤에 붙여넣으세요!

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"], # 모든 출신(*=All) 허용 (보안상 나중엔 특정 주소만 적어야 함)
    allow_methods=["*"],
    allow_headers=["*"],
)

이제 React가 데이터를 달라고 해도 문지기가 막지 않습니다.

7. [실습] '팀원 프로필' API 만들기: '오늘의 패션 추천' 페이지의 시작 👥

'오늘의 패션 추천' 페이지를 구성하기 위해, 팀원들의 정보(성별, 좋아하는 스타일 등)를 제공하는 API를 만들어봅시다. 이 데이터를 나중에 AI 스타일리스트에게 "이 친구의 취향에 맞춰서 추천해줘"라고 전달할 재료가 됩니다.

1단계: 팀원 데이터베이스 구축 (Python Dict)

# main.py 상단에 추가
members_db = {
    "ideabong": {
        "name": "이상봉",
        "gender": "남성",
        "style": "시티보이 룩",
        "location": "Seoul"  # 중요! 날씨 API에 넣을 값
    },
    "sunny": {
        "name": "박써니",
        "gender": "여성",
        "style": "러블리 캐주얼",
        "location": "Busan"   # 부산 날씨로 추천받게 됨
    }
}

2단계: API 상세 로직

# 1. 명단 전체 보기
@app.get("/members")
def get_all_members():
    return list(members_db.keys())

# 2. 특정 멤버 상세 보기 (Path Parameter 사용)
@app.get("/members/{username}")
def get_member_detail(username: str):
    member = members_db.get(username)
    if not member:
        return {"error": "팀원을 찾을 수 없습니다."}
    return member

8. 🔥 최종 심화: "내가 만든 데이터 + AI의 지능" 융합하기

이제 3챕터에서 만든 'AI 스타일리스트'를 한 단계 업그레이드할 시간입니다!

🎯 아키텍처 (데이터의 흐름)

React가 세 군데에서 데이터를 긁어와서 하나로 합칩니다.

Local API: 팀원 정보 (FastAPI)
External API: 날씨 정보 (Open-Meteo)
AI API: 추천 로직 (Gemini)

sequenceDiagram
    participant React as "⚛️ React App"
    participant MyServer as "🐍 My FastAPI"
    participant Weather as "☁️ Weather API"
    participant AI as "🤖 Gemini AI"

    Note over React: 1. 정보 수집
    React->>MyServer: "팀원(Bong) 스타일 뭐야?"
    MyServer-->>React: { style: "스트릿", gender: "남성" }

    React->>Weather: "오늘 날씨 어때?"
    Weather-->>React: { temp: 15도 }

    Note over React: 2. AI에게 의뢰
    React->>AI: "스트릿 패션 좋아하는 남성인데, 15도에 뭐 입을까?"
    AI-->>React: "후드티에 조거팬츠 추천!"

AI 협업 주문서 (Prompt)

이제 여러분의 React 코드를 고치기 위해 AI에게 이렇게 주문해보세요.

Prompt

우리가 만든 WeatherWidget을 확장해서 '오늘의 패션 추천 페이지(FashionPage)'를 만들고 싶어.

레이아웃: 화면 왼쪽에는 Select Box로 팀원 목록을 보여주고, 오른쪽 메인 화면에 결과가 나와야 해.
데이터 흐름:
- 페이지가 열리면 내 FastAPI(http://127.0.0.1:8000/members)에서 팀원 전체 목록을 가져와서 Select Box에 채워줘.
- 팀원을 선택하면 내 FastAPI(http://127.0.0.1:8000/members/{username})에서 정보를 가져와.
- 가져온 정보 중 location(지역)을 사용해서 날씨 API를 새로 호출해.
AI 추천:
- location의 날씨와 팀원의 style, gender를 모두 합쳐서 Gemini에게 '구체적인 옷차림 추천 내용(텍스트)'을 알려달라고 해줘.
디자인: 전체적으로 패션 매거진처럼 세련된 UI로 짜줘.

4부 마무리: 연결의 힘

여러분은 이제 고립된 개발자가 아닙니다.

나의 데이터(FastAPI)를 세상에 공개할 수 있고,
세상의 데이터(날씨 API)를 내 것으로 가져와서,
최신 지능(Gemini)을 결합해 하나의 거대한 서비스를 만들 줄 알게 되었습니다.

이것이 바로 현대 웹 서비스의 아키텍처이자, AI 에이전트 시대의 개발 방식입니다. 🚀