software

데이터 엔지니어를 위한 REST API 호출: 실용적인 예제 가이드

발행: (2025년 12월 14일 오전 09:02 GMT+9)
8 min read
원문: Dev.to

Source: Dev.to

소개

데이터 엔지니어는 데이터베이스만 다루는 경우는 드뭅니다. 현대 데이터 파이프라인은 REST API를 통해 데이터를 자주 수집합니다—SaaS 도구(Salesforce, Jira, Google Analytics)에서 데이터를 끌어오든, 내부 마이크로서비스이든, 서드파티 제공자이든 말이죠.

REST API가 어떻게 작동하고 효율적으로 상호작용하는지를 이해하는 것은 핵심 데이터 엔지니어링 스킬입니다.

이 가이드에서는 다음을 다룹니다:

  • REST API가 무엇인지 (간단하고 실용적으로)
  • 데이터 엔지니어 관점에서 본 일반적인 REST 메서드
  • 인증 패턴
  • 페이지네이션, 필터링, 그리고 레이트 제한
  • Python을 활용한 실제 예제
  • 프로덕션 데이터 파이프라인을 위한 모범 사례

REST API란? (데이터 엔지니어 관점)

REST(Representational State Transfer) API는 HTTP를 사용해 시스템 간에 표준 메서드로 통신할 수 있게 해줍니다.

데이터 엔지니어 입장에서 보면:

  • REST API는 데이터 소스이다
  • JSON이 가장 흔한 데이터 포맷이다
  • API는 종종 증분, 페이지네이션, 레이트 제한이 적용된다
  • API는 데이터 레이크, 웨어하우스, 스트리밍 시스템에 데이터를 공급한다

데이터 엔지니어가 주로 사용하는 핵심 REST HTTP 메서드

메서드데이터 엔지니어 사용법
GET데이터 조회 (가장 일반적)
POST파라미터 전송, 리소스 생성, 복잡한 쿼리
PUT기존 리소스 업데이트
DELETE파이프라인에서는 거의 사용되지 않음

데이터 엔지니어링에서는 GET과 POST가 전체의 약 90 %를 차지합니다.

REST API 요청의 구조

전형적인 REST API 호출은 다음과 같은 형태를 가집니다:

GET https://api.example.com/v1/orders?start_date=2025-01-01&limit=100

구성 요소

  • Base URL: https://api.example.com
  • Endpoint: /v1/orders
  • Query Parameters: start_date, limit
  • Headers: 인증, 콘텐츠 타입
  • HTTP Method: GET / POST

예제 1: 간단한 GET 요청 (데이터 가져오기)

사용 사례

외부 시스템에서 일일 매출 데이터를 가져옵니다.

API 요청

GET https://api.company.com/v1/sales

Python 예제 (requests 라이브러리)

import requests

url = "https://api.company.com/v1/sales"

headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

전형적인 JSON 응답

{
  "sales": [
    {
      "order_id": 101,
      "amount": 250.50,
      "currency": "USD",
      "order_date": "2025-01-10"
    }
  ]
}

이 JSON은 이후에:

  • 평탄화
  • 변환
  • 데이터 레이크 또는 웨어하우스에 저장

예제 2: 쿼리 파라미터 (데이터 필터링)

사용 사례

증분 데이터를 끌어와서 과거 레코드를 재처리하지 않도록 합니다.

GET /v1/sales?start_date=2025-01-01&end_date=2025-01-31

Python 코드

params = {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
}

response = requests.get(url, headers=headers, params=params)
sales_data = response.json()

✅ 모범 사례: 파이프라인은 항상 증분 방식으로 설계하세요.

예제 3: POST 요청 (복잡한 쿼리)

일부 API는 필터가 복잡할 경우 POST를 요구합니다.

API 호출

POST /v1/sales/search

Payload

{
  "region": ["US", "EU"],
  "min_amount": 100,
  "date_range": {
    "from": "2025-01-01",
    "to": "2025-01-31"
  }
}

Python 예제

payload = {
    "region": ["US", "EU"],
    "min_amount": 100,
    "date_range": {
        "from": "2025-01-01",
        "to": "2025-01-31"
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

인증 방법 (매우 중요)

1. API 키 인증

Authorization: ApiKey abc123

2. 베어러 토큰 (OAuth 2.0)

Authorization: Bearer eyJhbGciOi...

3. 기본 인증 (덜 안전)

requests.get(url, auth=("username", "password"))

🔐 데이터 엔지니어 팁
자격 증명은 다음에 저장하세요:

  • 환경 변수
  • 비밀 관리 서비스(AWS Secrets Manager, Azure Key Vault)

예제 4: 페이지네이션 (API에서 매우 흔함)

대부분의 API는 요청당 반환 결과 수를 제한합니다.

페이지네이션이 포함된 API 응답

{
  "data": [...],
  "page": 1,
  "total_pages": 10
}

Python 페이지네이션 로직

all_data = []
page = 1

while True:
    params = {"page": page, "limit": 100}
    response = requests.get(url, headers=headers, params=params)
    result = response.json()

    all_data.extend(result["data"])

    if page >= result["total_pages"]:
        break

    page += 1

✅ 항상 페이지네이션을 처리하세요. 그렇지 않으면 데이터가 누락됩니다.

예제 5: 레이트 제한 처리

API는 종종 요청 수를 제한합니다:

429 Too Many Requests

재시도 로직 예시

import time

response = requests.get(url, headers=headers)

if response.status_code == 429:
    time.sleep(60)  # 간단한 백오프
    response = requests.get(url, headers=headers)

📌 프로덕션 파이프라인에서는 다음을 사용해야 합니다:

  • 지수 백오프
  • 재시도 제한

예제 6: 오류 처리 (파이프라인에 필수)

response = requests.get(url, headers=headers)

if response.status_code != 200:
    raise Exception(
        f"API failed with status {response.status_code}: {response.text}"
    )

주요 HTTP 상태 코드

  • 200 – 성공
  • 400 – 잘못된 요청
  • 401 – 인증 실패
  • 404 – 찾을 수 없음
  • 500 – 서버 오류

데이터 파이프라인에서의 REST API 데이터 흐름

REST API
   ↓
Python / Spark Job
   ↓
Raw Zone (JSON)
   ↓
Transformation (Flattening, Cleaning)
   ↓
Data Warehouse (Snowflake / BigQuery / Redshift)

데이터 엔지니어를 위한 모범 사례

  • ✔ 항상 멱등(idempotent) 파이프라인 설계
  • ✔ 요청/응답 메타데이터 로깅
  • ✔ 원시 API 응답을 재처리를 위해 저장
  • ✔ 증분 로드 사용(타임스탬프, ID)
  • ✔ 실패 및 지연 시간 모니터링
  • ✔ API 레이트 제한을 준수

결론

REST API는 데이터 엔지니어에게 주요 데이터 수집 메커니즘입니다. 인증, 페이지네이션, 재시도, 오류 처리를 포함한 REST 호출을 마스터하면 파이프라인을 신뢰성 높고, 확장 가능하며, 프로덕션 준비 상태로 만들 수 있습니다. REST API에 대한 탄탄한 이해는 새로운 데이터 소스를 통합하는 작업을 크게 단순화합니다.

Back to Blog

관련 글

더 보기 »