부록 E18: API와 데이터 수집

이 장에서 배울 것

이번 장에서는 API와 데이터 수집을 배웁니다. API는 프로그램이 다른 프로그램이나 서버에 정해진 방식으로 요청을 보내고 데이터를 받는 통로입니다. 생물정보학에서는 공개 데이터베이스에서 유전자, 단백질, 논문, 변이 정보를 가져올 때 API를 자주 씁니다.

핵심 용어를 먼저 정리하겠습니다.

• API(application programming interface): 프로그램끼리 정해진 규칙으로 데이터를 주고받게 해 주는 통로입니다. 앞으로는 API라고 부르겠습니다.
• 요청(request): 데이터를 달라고 서버에 보내는 메시지입니다.
• 응답(response): 서버가 돌려주는 결과입니다.
• REST API: 인터넷 주소와 HTTP 방식으로 데이터를 요청하는 API 형태입니다.
• JSON: key-value 구조로 데이터를 표현하는 텍스트 형식입니다.
• XML: 태그를 이용해 데이터를 표현하는 텍스트 형식입니다.
• 파싱(parsing): 받은 데이터에서 필요한 정보를 꺼내는 작업입니다.
• rate limit: 서버가 너무 많은 요청을 막기 위해 정한 요청 제한입니다.
• 페이지네이션(pagination): 결과가 많을 때 여러 페이지로 나누어 받는 방식입니다.
• 캐시(cache): 한 번 받은 데이터를 저장해 두고 다시 쓰는 방식입니다.

가장 쉬운 비유: 식당 주문 창구

API는 식당 주문 창구와 비슷합니다. 손님은 아무 말이나 하는 것이 아니라 메뉴판의 규칙에 맞춰 주문합니다. “김치찌개 하나 주세요”라고 요청하면 식당은 김치찌개를 줍니다.

데이터 서버도 비슷합니다. 정해진 주소와 규칙에 맞춰 요청하면, 서버는 JSON이나 XML 같은 형식으로 데이터를 돌려줍니다.

URL은 데이터 요청 주소입니다

웹사이트 주소처럼 보이는 URL은 데이터 요청 주소가 될 수 있습니다.

https://example.org/api/gene/TP53

이 주소는 “TP53 유전자 정보를 주세요”라는 요청처럼 설계될 수 있습니다. 실제 API마다 주소 규칙은 다릅니다. 그래서 API 문서를 읽는 습관이 중요합니다.

JSON 이해하기

JSON은 파이썬 딕셔너리와 비슷하게 생겼습니다.

{
  "gene": "TP53",
  "organism": "human",
  "chromosome": "17"
}

여기서 gene, organism, chromosome은 key이고, 오른쪽 값은 value입니다. 파이썬에서는 JSON을 딕셔너리처럼 다룰 수 있습니다.

data = {
    "gene": "TP53",
    "organism": "human",
    "chromosome": "17"
}

print(data["gene"])

결과는 다음과 같습니다.

TP53

파이썬으로 API 요청하기

파이썬에서는 requests 라이브러리를 자주 씁니다.

import requests

url = "https://example.org/api/gene/TP53"
response = requests.get(url)
data = response.json()

print(data)

여기서 requests.get(url)은 해당 주소로 요청을 보내는 코드입니다. response.json()은 응답을 JSON으로 해석해 파이썬 객체로 바꾸는 코드입니다.

실제 생물정보학에서는 NCBI, Ensembl, UniProt 같은 데이터베이스 API를 사용할 수 있습니다. 다만 각 사이트마다 주소와 요청 규칙이 다르므로 공식 문서를 확인해야 합니다.

XML도 만날 수 있습니다

XML은 태그로 데이터를 감싸는 형식입니다.

<gene>
  <name>TP53</name>
  <organism>human</organism>
</gene>

JSON보다 길어 보이지만, 생물학 데이터베이스에서는 XML 형식도 자주 등장합니다. 입문 단계에서는 “JSON은 딕셔너리처럼, XML은 태그 구조처럼 생겼다” 정도를 알면 됩니다.

rate limit: 너무 빨리 많이 요청하면 안 됩니다

공개 데이터베이스 서버는 많은 사람이 함께 씁니다. 짧은 시간에 너무 많은 요청을 보내면 서버에 부담을 줄 수 있습니다. 그래서 API는 보통 rate limit를 둡니다.

좋은 데이터 수집 코드는 다음 태도를 가져야 합니다.

필요한 데이터만 요청하기
요청 사이에 짧은 쉬는 시간 두기
이미 받은 데이터는 캐시하기
오류가 나면 무한 반복하지 않기
API 사용 규칙 확인하기

페이지네이션

검색 결과가 너무 많으면 한 번에 전부 주지 않고 여러 페이지로 나누어 줄 수 있습니다. 이것을 페이지네이션이라고 합니다.

예를 들어 1000개 결과가 있는데 한 번에 100개씩 준다면, 10번 요청해야 모든 결과를 받을 수 있습니다. 이때 다음 페이지 주소나 토큰을 잘 따라가야 합니다.

캐시와 재현성

API에서 받은 데이터는 시간이 지나면 바뀔 수 있습니다. 유전자 주석이나 단백질 정보가 업데이트될 수 있기 때문입니다. 그래서 중요한 분석에서는 언제, 어떤 API에서, 어떤 조건으로 데이터를 받았는지 기록해야 합니다.

캐시는 같은 요청을 반복하지 않기 위해 받은 결과를 저장하는 방식입니다. 서버 부담도 줄이고, 분석 재현성도 높일 수 있습니다.

실전 보강: API는 항상 정상 응답을 주지 않는다

API 요청은 인터넷을 통해 외부 서버에 질문하는 일입니다. 따라서 실패할 수 있습니다. 상태 코드(status code)는 요청 결과를 알려주는 숫자입니다.

200: 정상 응답
404: 요청한 주소나 자료를 찾을 수 없음
429: 너무 많이 요청해서 제한됨
500: 서버 쪽 오류

초보자는 requests.get(url).json()만 쓰고 끝내기 쉽지만, 실제 연구 코드에서는 상태 코드와 timeout을 확인해야 합니다.

response = requests.get(url, timeout=10)
if response.status_code == 200:
    data = response.json()
else:
    print(response.status_code)

실전 보강: 페이지네이션과 재현성 기록

API가 결과 10,000개를 한 번에 주지 않고 100개씩 나눠 줄 수 있습니다. 이것을 페이지네이션이라고 합니다. 첫 페이지만 저장하면 데이터가 일부만 수집됩니다.

또 API 데이터는 시간이 지나면 바뀔 수 있습니다. 그래서 다음 정보를 기록해야 합니다.

요청 URL
쿼리 조건
수집 날짜
API 버전
페이지 수
응답 파일 checksum 또는 저장 경로

숫자 감각: 페이지네이션 요청 수 계산하기

API 수집에서도 간단한 계산이 필요합니다. 검색 결과가 10,000개이고 API가 한 번에 100개씩만 돌려준다면 전체를 받으려면 최소 100번 요청해야 합니다.

전체 결과 수 = 10,000개
한 페이지 크기 = 100개
필요 페이지 수 = 10,000 / 100 = 100페이지

첫 페이지만 저장하면 전체의 1%만 수집한 셈입니다. 그래서 다음 페이지 토큰, 총 결과 수, 실제 저장한 개수를 함께 확인해야 합니다.

초보자가 자주 하는 오해

• 오해 1: API에서 받은 데이터는 항상 완전하다. 페이지네이션, rate limit, 오류 응답 때문에 일부만 받을 수 있습니다.
• 오해 2: JSON 구조는 영원히 같다. API 버전이 바뀌면 key 이름이나 구조가 바뀔 수 있습니다.
• 오해 3: 429가 뜨면 더 빠르게 재시도하면 된다. rate limit에 걸렸다는 뜻이므로 기다리거나 요청 속도를 줄여야 합니다.
• 오해 4: 캐시는 게으른 방식이다. 같은 요청을 반복하지 않고 재현성을 높이는 좋은 습관입니다.

이전 개념과 다음 개념의 연결

API로 받은 유전자 주석, 변이 정보, 문헌 정보는 E17 데이터베이스 구조로 정리할 수 있습니다. 수집 코드의 버전은 E19 Git으로 관리하고, 실행 환경은 E20으로 기록해야 합니다.

생물정보학에서 왜 중요한가

생물정보학 연구자는 모든 데이터를 직접 만들지 않습니다. 공개 데이터베이스에서 필요한 정보를 가져와 자신의 데이터와 합칩니다. 예를 들어 유전자 ID를 유전자 이름으로 바꾸거나, 변이에 질병 정보를 붙이거나, 단백질 기능 정보를 가져올 수 있습니다. API는 이런 작업을 자동화하게 해 줍니다.

미니 실습 블록: API로 받은 데이터를 파일과 로그로 남기기

이 실습은 API로 받은 데이터를 파일과 로그로 남기기를 직접 손으로 확인하는 연습입니다. 왜 필요한가 하면, API 데이터는 시간이 지나며 바뀔 수 있으므로 언제 어떤 주소에서 받았는지 기록해야 재현성이 생기기 때문입니다.

import requests
import json
from datetime import datetime

url = "https://example.org/api/gene/TP53"
response = requests.get(url)
data = response.json()

with open("results/tp53.json", "w") as f:
    json.dump(data, f, indent=2)

with open("results/api_log.txt", "a") as log:
    log.write(f"{datetime.now()}\t{url}\t{response.status_code}\n")

각 코드 요소의 의미를 풀어보면 다음과 같습니다. requests.get은 URL에 요청을 보내고, response.json()은 JSON 응답을 Python 객체로 바꿉니다. 로그에는 시간, URL, 상태코드를 남깁니다.

생물정보학/계산생물학에서 쓰이는 장면은 분명합니다. Ensembl, NCBI, UniProt 같은 데이터베이스에서 유전자·단백질 정보를 가져올 때 필요합니다.

흔한 오해 또는 주의점도 있습니다. API 결과를 매번 새로 받으면 데이터베이스 업데이트 때문에 과거 결과와 달라질 수 있습니다. 받은 원본 응답도 보관하는 것이 좋습니다.

핵심 정리

API는 프로그램이 데이터 서버에 정해진 방식으로 요청하고 응답을 받는 통로입니다. JSON과 XML은 API 응답에서 자주 보는 형식이며, 파이썬에서는 requests로 데이터를 가져올 수 있습니다. 좋은 데이터 수집은 rate limit, 페이지네이션, 캐시, 재현성 기록을 함께 고려해야 합니다.

문제 풀이

API와 데이터 수집

0 / 42

Gemini AI 채점

주관식 답안은 Gemini API로 채점합니다. API 키는 이 브라우저에만 저장됩니다.

API KEY 미등록

1. 1. [객관식] 객관식

   API의 설명으로 적절한 것은?

   선택지

   단백질을 접는 구조입니다. 프로그램끼리 정해진 규칙으로 데이터를 주고받게 해 주는 통로입니다. HTTP 상태 코드를 확인하지 않고 응답 본문만 바로 파싱하는 접근 페이지네이션을 무시하고 첫 페이지만 전체 결과로 보는 해석
2. 2. [객관식] 객관식

   요청(request)의 의미로 적절한 것은?

   선택지

   서버가 돌려준 최종 결과입니다. DNA의 염기쌍입니다. SQL의 테이블 행입니다. 데이터를 달라고 서버에 보내는 메시지입니다.
3. 3. [객관식] 객관식

   응답(response)의 의미로 적절한 것은?

   선택지

   서버가 요청에 대해 돌려주는 결과입니다. 429 응답을 더 빠른 재요청으로 해결하려는 접근 유전자 발현량의 표준편차입니다. 폴더의 절대경로입니다.
4. 4. [객관식] 객관식

   JSON의 설명으로 적절한 것은?

   선택지

   BAM 파일의 색인입니다. 단백질의 알파나선입니다. key-value 구조로 데이터를 표현하는 텍스트 형식입니다. RNA-seq의 품질 점수입니다.
5. 5. [객관식] 객관식

   XML의 설명으로 적절한 것은?

   선택지

   모든 값을 숫자 배열로만 저장하는 형식입니다. Python 반복문입니다. 태그를 이용해 데이터를 표현하는 텍스트 형식입니다. SQL 기본키입니다.
6. 6. [객관식] 객관식

   파싱(parsing)의 뜻으로 적절한 것은?

   선택지

   받은 데이터에서 필요한 정보를 꺼내는 작업입니다. 서버를 물리적으로 고치는 작업입니다. API 응답 구조가 시간이 지나도 절대 바뀌지 않는다고 보는 해석 세포를 염색하는 실험입니다.
7. 7. [객관식] 객관식

   rate limit의 목적은?

   선택지

   모든 데이터를 무조건 빠르게 삭제하기 위해서입니다. 수집 날짜와 쿼리 조건을 기록하지 않아도 재현 가능하다고 보는 해석 캐시를 쓰면 항상 최신 데이터 분석이 불가능하다고 보는 해석 서버에 너무 많은 요청이 몰리는 것을 막기 위해서입니다.
8. 8. [객관식] 객관식

   페이지네이션(pagination)의 설명으로 적절한 것은?

   선택지

   모든 데이터를 한 줄로 압축하는 방식입니다. 결과가 많을 때 여러 페이지로 나누어 받는 방식입니다. 세포를 종류별로 염색하는 방식입니다. 파일 이름을 바꾸는 방식입니다.
9. 9. [객관식] 객관식

   캐시(cache)의 설명으로 적절한 것은?

   선택지

   항상 서버에 같은 요청을 무한히 보내는 방식입니다. 모든 JSON을 삭제하는 방식입니다. read를 기준 유전체에 정렬하는 방식입니다. 한 번 받은 데이터를 저장해 두고 다시 쓰는 방식입니다.
10. 10. [객관식] 객관식

    requests.get(url)의 역할에 가까운 것은?

    선택지

    SQL 테이블을 조인하는 것입니다. 지정한 URL로 GET 요청을 보내는 것입니다. BAM 파일을 색인하는 것입니다. 단백질 구조를 접는 것입니다.
11. 11. [객관식] 객관식

    response.json()의 역할로 적절한 것은?

    선택지

    Python 파일을 삭제하는 것입니다. HTTP 상태 코드를 확인하지 않고 응답 본문만 바로 파싱하는 접근 응답을 JSON으로 해석해 파이썬 객체로 바꾸는 것입니다. 페이지네이션을 무시하고 첫 페이지만 전체 결과로 보는 해석
12. 12. [객관식] 객관식

    JSON 예시 { "gene": "TP53" }에서 gene은 무엇인가?

    선택지

    key입니다. 파일 확장자입니다. 서버 주소입니다. 품질 점수입니다.
13. 13. [객관식] 객관식

    JSON 예시 { "gene": "TP53" }에서 TP53은 무엇인가?

    선택지

    value입니다. SQL의 JOIN 키워드입니다. XML 태그 이름만입니다. BAM의 색인입니다.
14. 14. [객관식] 객관식

    공개 데이터베이스 API를 사용할 때 좋은 태도는?

    선택지

    짧은 시간에 무한히 요청하는 것입니다. 오류가 나도 무한 반복하는 것입니다. API 문서와 사용 규칙을 확인하고 필요한 만큼 요청하는 것입니다. 받은 데이터를 기록하지 않는 것입니다.
15. 15. [객관식] 객관식

    API에서 받은 데이터가 시간이 지나면 바뀔 수 있는 이유는?

    선택지

    JSON은 항상 사라지기 때문입니다. 데이터베이스 주석이나 정보가 업데이트될 수 있기 때문입니다. 컴퓨터가 숫자를 싫어하기 때문입니다. URL은 절대 변하지 않기 때문입니다.
16. 16. [객관식] 객관식

    재현성을 위해 API 데이터 수집 시 기록할 것으로 적절한 것은?

    선택지

    마우스 색상입니다. 429 응답을 더 빠른 재요청으로 해결하려는 접근 API 응답 구조가 시간이 지나도 절대 바뀌지 않는다고 보는 해석 언제, 어떤 API에서, 어떤 조건으로 받았는지입니다.
17. 17. [객관식] 객관식

    API로 가져올 수 있는 생물정보 예시로 적절한 것은?

    선택지

    책상 높이만입니다. 수집 날짜와 쿼리 조건을 기록하지 않아도 재현 가능하다고 보는 해석 유전자 주석, 단백질 기능, 변이 정보입니다. 컴퓨터 팬 소리만입니다.
18. 18. [객관식] 객관식

    XML 예시 <name>TP53</name>에서 태그 안 값은?

    선택지

    name만입니다. 괄호 전체입니다. 항상 비어 있습니다. TP53입니다.
19. 19. [객관식] 객관식

    페이지네이션에서 다음 페이지 토큰을 놓치면 생길 수 있는 문제는?

    선택지

    전체 결과 중 일부만 수집할 수 있습니다. 모든 결과가 자동으로 두 배가 됩니다. 서열이 단백질로 바뀝니다. 캐시를 쓰면 항상 최신 데이터 분석이 불가능하다고 보는 해석
20. 20. [객관식] 객관식

    API와 SQL의 차이에 대한 설명으로 적절한 것은?

    선택지

    API와 SQL은 모두 단백질 이름입니다. API는 서버에 정해진 방식으로 요청하는 통로이고, SQL은 데이터베이스 테이블에 질의하는 언어입니다. HTTP 상태 코드를 확인하지 않고 응답 본문만 바로 파싱하는 접근 API는 파일 삭제 명령이고 SQL은 그래프입니다.
21. 21. [객관식] 객관식

    API 응답 코드 429를 받았을 때 적절한 대응은?

    선택지

    더 빠르게 무한 반복 요청한다. 요청 속도를 줄이거나 기다렸다가 재시도한다. 응답을 정상 데이터로 간주한다. 페이지네이션을 무시하고 첫 페이지만 전체 결과로 보는 해석
22. 22. [객관식] 객관식

    API 응답 코드 404의 의미로 가장 적절한 것은?

    선택지

    요청한 주소나 자료를 찾을 수 없다는 뜻이다. 요청이 완벽히 성공했다는 뜻이다. 서버가 너무 많은 요청을 받았다는 뜻이다. JSON 파싱이 항상 성공했다는 뜻이다.
23. 23. [객관식] 객관식

    페이지네이션을 무시하고 첫 페이지만 저장하면 생기는 문제는?

    선택지

    결과가 자동으로 두 배 늘어난다. API 버전이 고정된다. rate limit이 영원히 사라진다. 전체 결과 중 일부만 수집될 수 있다.
24. 24. [객관식] 객관식

    다음 JSON에서 gene 값은?

    선택지

    gene 0.91 TP53 score
25. 25. [객관식] 객관식

    API 수집 코드에서 timeout=10을 주는 이유로 적절한 것은?

    선택지

    반드시 10개 유전자만 받기 위해서이다. 응답이 너무 오래 걸릴 때 무한 대기를 피하기 위해서이다. JSON key를 10글자로 제한하기 위해서이다. 결과 p-value를 10으로 만들기 위해서이다.
26. 26. [객관식] 객관식

    API 데이터 재현성을 위해 기록해야 할 정보로 부적절한 것은?

    선택지

    요청 URL과 쿼리 조건 수집 날짜와 API 버전 응답 파일 또는 캐시 경로 분석자가 그날 먹은 점심 메뉴
27. 27. [객관식] 객관식

    같은 API 요청을 반복하지 않기 위해 응답을 파일로 저장해 두는 전략은?

    선택지

    캐시(cache) 정규화(normalization) 클러스터링(clustering) 중복 read 표시
28. 28. [객관식] 객관식

    API 응답 JSON 구조가 바뀌었을 때 깨지기 쉬운 코드는?

    선택지

    상태 코드를 확인하는 코드 예외를 기록하는 코드 특정 key가 항상 존재한다고 가정하고 바로 접근하는 코드 수집 날짜를 기록하는 코드
29. 29. [객관식] 객관식

    다음 코드에서 문제될 수 있는 점은?

    선택지

    JSON을 절대 읽을 수 없다. url 변수를 항상 삭제한다. 상태 코드, timeout, 오류 응답 처리를 확인하지 않는다. API를 반드시 SQL로 바꾼다.
30. 30. [객관식] 객관식

    공개 데이터베이스 API에서 오늘 받은 결과와 1년 뒤 받은 결과가 달라질 수 있는 이유는?

    선택지

    데이터베이스와 API가 업데이트될 수 있기 때문이다. 429 응답을 더 빠른 재요청으로 해결하려는 접근 URL은 항상 매일 랜덤하게 삭제되기 때문이다. 인터넷 요청은 기록할 필요가 없기 때문이다.
31. 31. [실전] 객관식

    API 요청 로그에 URL과 날짜를 남기는 이유는?

    선택지

    원본 데이터를 덮어써서 파일 수를 줄이는 것이다. 분석 결과를 해석 없이 바로 생물학적 결론으로 확정하는 것이다. 나중에 어떤 데이터 출처와 시점으로 분석했는지 추적하기 위해서다. 샘플 ID와 파일명을 일부러 무작위로 바꾸는 것이다.
32. 32. [실전] 객관식

    HTTP status code가 200이 아니라면 우선 해야 할 일은?

    선택지

    원본 데이터를 덮어써서 파일 수를 줄이는 것이다. 분석 결과를 해석 없이 바로 생물학적 결론으로 확정하는 것이다. 샘플 ID와 파일명을 일부러 무작위로 바꾸는 것이다. 응답이 정상인지 확인하고 오류 메시지나 요청 주소를 점검한다.
33. 주관식 33. [응용] 주관식 · Gemini 채점

    API를 식당 주문 창구 비유로 설명하라.
34. 주관식 34. [응용] 주관식 · Gemini 채점

    JSON과 XML의 차이를 간단히 설명하라.
35. 주관식 35. [응용] 주관식 · Gemini 채점

    rate limit를 지켜야 하는 이유를 설명하라.
36. 주관식 36. [응용] 주관식 · Gemini 채점

    캐시가 API 데이터 수집에서 유용한 이유를 설명하라.
37. 주관식 37. [응용] 주관식 · Gemini 채점

    페이지네이션이 있는 API에서 주의할 점을 설명하라.
38. 주관식 38. [응용] 주관식 · Gemini 채점

    API에서 받은 생물정보를 분석에 사용할 때 기록해야 할 것을 설명하라.
39. 주관식 39. [응용] 주관식 · Gemini 채점

    API 수집 코드에서 상태 코드, timeout, 페이지네이션을 확인해야 하는 이유를 설명하라.
40. 주관식 40. [응용] 주관식 · Gemini 채점

    API로 받은 데이터를 재현 가능하게 저장하기 위한 기록 항목을 쓰라.
41. 주관식 41. [실습] 주관식 · Gemini 채점

    API 응답 JSON을 results/tp53.json에 저장하는 Python 코드의 핵심 부분을 작성하라.
42. 주관식 42. [실습] 주관식 · Gemini 채점

    API 데이터 수집에서 provenance가 중요한 이유를 설명하라.