Skip to content

제3.2장: 첫 API 엔드포인트 생성

학습 시간: 30분

1. 엔드포인트: 데이터 도킹 포트

우리 API가 우주 정거장이라고 상상해 보세요. 엔드포인트(종점)는 특정 유형의 우주선을 위해 설계된 특정 도킹 포트입니다.

  • 포트 №1 — 화물선용 (행성 데이터).
  • 포트 №2 — 탐사선용 (임무 데이터).
  • 포트 №3 — 여객 셔틀용 (우주 비행사 데이터).

각 엔드포인트는 특정 리소스에 대한 특정 작업을 담당하는 고유한 URL입니다.

💡 우주 비유: GET /spaceships — 이는 "지상 관제 센터 → 정거장: 모든 도킹된 우주선 목록을 보고하십시오"라는 명령어입니다. 이 엔드포인트는 리소스 컬렉션을 반환합니다.

2. "우주 함대" 생성

아직 데이터베이스가 없으므로 Python 딕셔너리 형태의 간단한 우주선 목록으로 "시뮬레이션"을 만들겠습니다.

main.py를 열고 app 정의 앞에 다음 코드를 추가하세요: 

# main.py

# 단계 1: 데이터베이스 시뮬레이션 생성
db_spaceships = {
    1: {
        "name": "Voyager-1",
        "type": "탐사선",
        "launch_year": 1977,
        "status": "활성"
    },
    2: {
        "name": "Hubble Space Telescope",
        "type": "망원경",
        "launch_year": 1990,
        "status": "활성"
    },
    3: {
        "name": "ISS",
        "type": "정거장",
        "launch_year": 1998,
        "status": "궤도"
    }
}

# ... 여기에 app = FastAPI() 코드 ...
이것이 우리가 작업할 "우주선 등록부"입니다.

3. 첫 번째 엔드포인트: 우주선 목록

이제 우리 함대 전체를 반환하는 엔드포인트를 만들겠습니다.

main.py의 @app.get("/") 다음에 다음 코드를 추가하세요: 

# main.py

# ... db_spaceships, FastAPI, app 및 read_root() 코드 ...

@app.get("/spaceships")
def get_spaceships():
    """
    등록된 모든 우주선 목록을 반환합니다.
    """
    return db_spaceships

  • @app.get("/spaceships"): 새 경로를 생성했습니다. 이제 /spaceships URL에 대한 GET 요청은 get_spaceships 함수에 의해 처리됩니다.
  • return db_spaceships: FastAPI는 Python 딕셔너리를 유효한 JSON 응답으로 자동 변환합니다.

4. 새 도킹 포트 작동 확인

만약 uvicorn 서버가 --reload 플래그와 함께 여전히 실행 중이라면, 이미 재로드되어 작동 준비가 완료되었습니다. 그렇지 않다면 다시 시작하십시오: 

uvicorn main:app --reload

단계 1: 브라우저에서 확인

브라우저에서 http://127.0.0.1:8000/spaceships 주소를 엽니다. JSON 형식으로 우주선 전체 목록이 표시되어야 합니다: 

{
  "1": {
    "name": "Voyager-1",
    "type": "Зонд",
    "launch_year": 1977,
    "status": "Активен"
  },
  "2": {
    "name": "Hubble Space Telescope",
    "type": "Телескоп",
    "launch_year": 1990,
    "status": "Активен"
  },
  "3": {
    "name": "ISS",
    "type": "Станция",
    "launch_year": 1998,
    "status": "На орбите"
  }
}

단계 2: 자동 문서에서 확인

http://127.0.0.1:8000/docs로 이동하세요. 문서에 GET /spaceships 엔드포인트에 대한 새 섹션이 나타난 것을 볼 수 있습니다. "Try it out"을 클릭하고 "Execute"를 눌러 거기서 바로 테스트할 수 있습니다!

5. 매개변수가 있는 엔드포인트: 특정 우주선 데이터

"보이저-1"에 대한 데이터만 필요하다면 어떨까요? 이를 위해 경로 매개변수(path parameter)를 사용하여 엔드포인트를 만들겠습니다.

main.py에 다음 코드를 추가하세요: 

# main.py

# ... 나머지 코드 ...

@app.get("/spaceships/{ship_id}")
def get_spaceship(ship_id: int):
    """
    ID를 사용하여 특정 우주선에 대한 데이터를 반환합니다.
    """
    return db_spaceships.get(ship_id)

  • "/spaceships/{ship_id}": 중괄호 {}는 ship_id가 URL에서 전달될 변수임을 FastAPI에 알려줍니다.
  • ship_id: int: 이것은 타입 힌트(type hint)입니다. FastAPI는 전달된 ID가 정수인지 자동으로 확인합니다. 만약 누군가 /spaceships/voyager를 요청하면, FastAPI는 유효성 검사 오류 422 Unprocessable Entity를 반환할 것입니다. 이것은 마법입니다!

확인:

http://127.0.0.1:8000/spaceships/2를 엽니다. "허블" 망원경에 대한 데이터만 얻을 수 있습니다. 만약 http://127.0.0.1:8000/spaceships/99를 열면, 해당 우주선이 없으므로 null을 받게 됩니다.

정리 퀴즈

1. API의 엔드포인트는...

2. `@app.get("/users")` 데코레이터는 무엇을 합니까?

c) 모든 데코레이터 목록 가져오기

3. 경로에 `"/items/{item_id}"`라는 표시는 무엇을 의미합니까?

4. 함수에 `ship_id: int` 타입 힌트가 필요한 이유는 무엇입니까?

5. `/spaceships/abc`를 요청했는데 FastAPI가 `int`를 예상한다면 어떻게 됩니까?

🚀 장 요약:

API 우주 정거장에 두 개의 "도킹 포트"를 성공적으로 만들었습니다:

  • 🛰️ 모든 우주선 목록을 가져오는 포트 (/spaceships)
  • 🔭 특정 우주선에 대한 데이터를 가져오는 포트 (/spaceships/{ship_id})

또한 FastAPI의 자동 타입 유효성 검사의 강력함을 확인했으며, 이는 API를 잘못된 요청으로부터 보호합니다.

내비게이션 시스템이 설정되었습니다! 다음 장에서는 Pydantic을 사용하여 우리 우주선의 "청사진"을 만들어 API를 더욱 스마트하고 견고하게 만들 것입니다.

📌 확인: - uvicorn 서버가 실행 중이며 작동합니다. - URL http://127.0.0.1:8000/spaceships가 우주선 목록이 포함된 JSON을 반환합니다. - URL http://127.0.0.1:8000/spaceships/1가 "보이저-1호"에 대한 데이터를 반환합니다. - URL http://127.0.0.1:8000/docs가 두 개의 새로운 엔드포인트를 보여줍니다.

⚠️ 오류가 발생하면:

  • 404 Not Found: 브라우저와 @app.get(...) 데코레이터에서 URL이 올바르게 입력되었는지 확인하세요.
  • 코드 오류: 구문, 특히 Python의 들여쓰기와 딕셔너리의 쉼표를 주의 깊게 확인하세요.