5강 / 20강

API 를 두드린다 — 첫 요청

Perturb-seq Explorer API · FastAPI · 엔드포인트 6개

이 자료는 파일로 주고받기엔 큽니다. 그래서 서버에 올려 두고 API 로 필요한 조각만 꺼내 씁니다.

http://192.168.219.45:8500/api/perturb/LAT
└──────── 서버 ────────┘└──── 무엇을 달라는지 ────┘

주소 하나를 보내면 JSON 한 덩이가 돌아옵니다. 그게 전부입니다.

돌아오는 것은 파이썬 딕셔너리입니다. JSON 과 모양이 같아서 그대로 다룰 수 있습니다.

Python 브라우저에서 실행

# 가장 간단한 요청부터.
import pseq

s = pseq.stats()          #  GET /api/stats  와 같습니다
print(type(s).__name__, "가 돌아옵니다")
print()
for k, v in s.items():
    if isinstance(v, list):
        print(k.ljust(26), len(v), "개")
    else:
        print(k.ljust(26), v)

고등학생엔드포인트가 여섯 개

엔드포인트는 "무엇을 물어볼지"에 따라 나뉜 창구입니다.

물어보는 것	얻는 것
이 유전자를 껐을 때	세포 수, 억제 정도, 하류 변화 수
여러 유전자를 한꺼번에	비교 표 (16강)
클러스터	기능적으로 묶인 유전자 무리 (14강)
질환 연결	GWAS 농축 결과 (15강)

중요한 것은 돌려주는 것이 이미 계산된 요약이라는 점입니다. 원래 세포 하나하나의 자료가 아니라, "이 유전자를 껐을 때 몇 개가 올라가고 몇 개가 내려갔다" 같은 정리된 숫자예요.

`conditions`·`clusters`·`diseases`·`downstream`·`summary` 다섯 칸입니다. 앞으로 열다섯 강이 이 다섯 칸을 하나씩 뜯는 일입니다.

Python 브라우저에서 실행

# 표적 하나를 통째로 받아 봅니다.
import pseq

r = pseq.perturb("LAT")        #  GET /api/perturb/LAT

print("최상위 열쇠:", list(r.keys()))
print()
print("summary:")
for k, v in r["summary"].items():
    print("   ", k.ljust(20), v)

고등학생JSON을 읽는 법

서버가 돌려주는 것은 JSON이라는 형식입니다. 중괄호와 따옴표로 이루어진 텍스트인데, 구조가 단순해요.

기호	뜻	파이썬으로
`{ }`	이름–값 쌍의 묶음	딕셔너리
`[ ]`	순서 있는 목록	리스트
`"..."`	글자	문자열
숫자	숫자	int / float
`null`	값이 없음	None

마지막 줄이 중요합니다 — null과 0은 다릅니다. 8강의 주제와 직결돼요.

`summary` 를 바로 꺼내 썼다면 여기서 KeyError 로 죽었을 겁니다.

Python 브라우저에서 실행

# 없는 유전자를 물어보면.
import pseq

r = pseq.perturb("MAT2A")      # 파이프라인 표적인데 이 스크린에는 없습니다

print("돌아온 열쇠:", list(r.keys()))
print()
if "error" in r:
    print("오류:", r["error"])
    print("이런 걸 찾으셨나요:", r["suggestions"])

고등학생요청이 실패할 때

API를 두드리면 항상 성공하지는 않습니다. 상태 코드로 무슨 일인지 알려 줘요.

코드	뜻	할 일
200	성공	—
404	그런 것이 없다	유전자 이름 확인 — 별칭일 수도
422	요청 형식이 틀림	파라미터 확인
500	서버 문제	잠시 뒤 재시도
연결 실패	서버가 안 뜸	주소·네트워크 확인

404가 특히 헷갈립니다. "이 유전자가 스크린에 없다"인지 "이름을 틀렸다"인지 구분해야 해요. 유전자 이름은 별칭이 많아서(예전 이름, 새 이름) 자주 어긋납니다.

🤔 확인 문제

이 API 에서 없는 유전자를 물었을 때 일어나는 일은?

해설 상태 코드는 200 입니다. 그래서 상태 코드만 보고 성공으로 판단하면 그다음 줄에서 KeyError 로 죽습니다. "error" in r 로 갈라야 합니다.

🤔 확인 문제

표적 하나의 전체 프로파일을 받는 엔드포인트는?

해설 /api/perturb/<유전자> 가 중심 엔드포인트입니다. 조건별 결과 · 클러스터 · 질환 · 하류 유전자 · 요약이 한 번에 옵니다.