Connecting to a Poorly Documented API

목표

문서가 부실한 고객사 API 에 붙어, 명세에 없는 사실까지 전수 조사로 확인하고 재시도까지 처리할 수 있게 됩니다.

왜 중요한가

새 API 에 붙을 때의 첫 작업은 코드를 쓰는 것이 아니라 전수 조사입니다. 모든 페이지를 한 번 돌면서 총 건수, 합계, 각 필드의 결측 건수를 세어 봅니다. 이 한 번이 이후 몇 주의 디버깅을 없앱니다. "총 60건 중 6건은 region 이 비어 있습니다. 이 건들을 어떻게 처리할까요" 를 첫 주에 물으면, 나중에 지역별 합계가 안 맞는다는 신고가 오지 않습니다.

페이지네이션에서 가장 흔한 버그는 total 로 페이지 수를 계산하면서 나눗셈의 나머지를 잊는 것입니다. 마지막 페이지가 통째로 빠지고, 그 사실은 합계가 미묘하게 작다는 형태로만 드러나서 발견이 늦습니다. 그래서 4번에서는 계산값을 믿지 말고 실제로 돌며 세어 검증합니다.

재시도에서는 대상 구분이 중요합니다. 5xx 와 네트워크 오류는 일시적일 수 있어 재시도 대상이지만, 4xx 는 요청을 고치지 않으면 몇 번을 보내도 같은 결과라 재시도가 부하만 올립니다.

API 명세 (위키에 적힌 전부)

• GET /health → {"status": "ok"}
• GET /meta → {"version", "page_size", "total"}
• GET /orders?page=N → {"page", "page_size", "total", "has_next", "items": [{id, customer, amount, region}]} — page 는 1부터
• GET /flaky → 가끔 실패한다고만 적혀 있음

단계

1. /opt/app/api.py 를 실행해 127.0.0.1:8002/health 가 200 을 반환하게 만드세요.
2. /meta 의 version 값을 /root/api/version.txt 에 적으세요.
3. 전체 페이지 수를 계산해 /root/api/pages.txt 에 적으세요.
4. 모든 페이지를 실제로 순회해 수집한 레코드 총 개수를 /root/api/count.txt 에 적으세요.
5. 모든 레코드의 amount 합계를 /root/api/sum.txt 에 적으세요.
6. region 이 빈 문자열인 레코드 수를 /root/api/no_region.txt 에 적으세요.
7. /flaky 를 재시도해 끝내 받아 낸 상태 코드를 /root/api/flaky_ok.txt 에 적으세요.
8. /root/api/report.md 에 버전, 총 건수, 금액 합계를 정리하세요.

참고

• python3 /opt/app/api.py & 로 띄웁니다.
• curl -s http://127.0.0.1:8002/orders?page=1 | python3 -m json.tool 로 구조를 먼저 보세요.
• 반복: for p in $(seq 1 6); do curl -s "http://127.0.0.1:8002/orders?page=$p"; done
• 흔한 실수 1: 3번에서 나머지를 버려 마지막 페이지를 빠뜨리는 것.
• 흔한 실수 2: 4번에서 /meta 의 total 을 그대로 베끼는 것. 실제로 순회해 세는 것이 이 단계의 목적입니다.

주문 API 띄우기

/opt/app/api.py 를 실행해 127.0.0.1:8002/health 가 200 을 반환하게 만드세요.

/opt/app/api.py 를 실행하면 127.0.0.1:8002 에서 대기합니다. /health 로 확인하세요.

API 버전 확인하기

/meta 의 version 값을 /root/api/version.txt 에 적으세요.

/meta 응답이 JSON 입니다. version 필드 값만 뽑으세요. jq 나 python3 를 쓰면 편합니다.

전체 페이지 수 계산하기

전체 페이지 수를 계산해 /root/api/pages.txt 에 적으세요.

/meta 의 total 과 page_size 로 계산합니다. 나머지가 있으면 페이지가 하나 더 있습니다.

전 페이지 순회해 건수 세기

모든 페이지를 실제로 순회해 수집한 레코드 총 개수를 /root/api/count.txt 에 적으세요.

실제로 모든 페이지를 돌며 items 를 세세요. total 필드를 그대로 베끼지 말고 검증하는 것이 요점입니다.

금액 합계 구하기

모든 레코드의 amount 합계를 /root/api/sum.txt 에 적으세요.

모든 페이지의 items 에서 amount 를 더합니다.

결측 레코드 세기

region 이 빈 문자열인 레코드 수를 /root/api/no_region.txt 에 적으세요.

문서에 없는 결측입니다. region 이 빈 문자열인 레코드가 몇 건인지 세세요.

불안정한 엔드포인트 통과하기

/flaky 를 재시도해 끝내 받아 낸 상태 코드를 /root/api/flaky_ok.txt 에 적으세요.

/flaky 는 처음 몇 번 503 을 냅니다. 200 이 올 때까지 재시도하고 최종 상태 코드를 적으세요.

연동 결과 보고서 쓰기

/root/api/report.md 에 버전, 총 건수, 금액 합계를 정리하세요.

버전, 총 건수, 금액 합계가 모두 들어가야 합니다. 첫 주에 고객에게 보낼 문서라고 생각하세요.