API를 만들 때 오류가 나면 무조건 500을 주거나, 반대로 무조건 200에 {"success": false}를 담아 보내는 경우가 있다. 둘 다 나중에 문제가 된다. 이 글은 HTTP 상태 코드를 실제 상황에 어떻게 대응시킬지와, 오류 응답 본문을 어떻게 설계할지를 정리한다.200에 실패를 담으면 안 되는 이유먼저 가장 흔한 안티패턴부터. 모든 응답을 200으로 주고 본문에 성공 여부를 담는 방식이다.HTTP/1.1 200 OK{"success": false, "message": "권한이 없습니다"}동작은 한다. 문제는 HTTP 계층의 도구들이 전부 무력해진다는 것이다.로드 밸런서와 모니터링은 상태 코드로 오류율을 센다. 전부 200이면 오류율이 0%로 보인다. 실제로는 절반이 실패하고 있어도 대시보..

API를 만들고 나면 언젠가 바꿔야 할 때가 온다. 필드 이름을 고치거나, 응답 구조를 바꾸거나, 없애야 할 엔드포인트가 생긴다. 그런데 이미 쓰고 있는 클라이언트가 있으면 마음대로 바꿀 수 없다. 이 글은 버저닝 방식의 선택지와, 그보다 먼저 고민해야 할 "버전을 올리지 않고 바꾸는 법"을 다룬다.깨는 변경과 깨지 않는 변경먼저 구분이 필요하다. 모든 변경이 새 버전을 요구하지는 않는다.깨지 않는 변경(추가) 은 대체로 안전하다. 새 엔드포인트 추가, 응답에 새 필드 추가, 선택적 요청 파라미터 추가가 여기 속한다. 기존 클라이언트는 모르는 필드를 무시하면 되므로 영향이 없다.깨는 변경은 이런 것들이다. 필드 삭제나 이름 변경, 타입 변경(문자열 → 숫자), 필수 파라미터 추가, 기본값 변경, 오류 코..

목록 API에 ?page=1&size=20을 붙이는 것은 익숙한 방식이다. 그런데 데이터가 쌓이면 뒤쪽 페이지가 느려지고, 스크롤하는 동안 같은 항목이 두 번 보이거나 어떤 항목은 아예 건너뛰어진다. 이 글은 오프셋 방식의 두 가지 구조적 문제와, 커서 방식이 그걸 어떻게 푸는지를 다룬다.오프셋은 건너뛴 만큼 읽는다LIMIT 20 OFFSET 100000이 어떻게 동작하는지 알면 문제가 보인다. 데이터베이스는 10만 개를 건너뛰기 위해 실제로 읽는다. 읽고 버린다. 그리고 그다음 20개를 돌려준다.SELECT * FROM posts ORDER BY created_at DESC LIMIT 20 OFFSET 100000;그래서 페이지 번호가 커질수록 느려진다. 1페이지는 빠르고 5000페이지는 느리다. 인덱..