이런 실수의 방법론
구체적인 실수에 들어가기 전에, 내가 API 디자인 실패를 어떻게 분류하는지 이해해야 한다. 나는 단순히 일화를 수집하지 않는다 — 산업, 팀 규모, 기술 스택에 걸쳐 패턴을 추적한다. 오늘 아침 현재 내 스프레드시트에는 847개의 항목이 있다. 각 항목은 실수 카테고리, 팀 규모, 발견까지 걸린 시간(문제를 알게 되기까지 걸린 시간), 수정 시간, 예상 비즈니스 영향을 포함한다. 데이터는 익명 처리했지만 패턴은 분명하다. 실수는 세 가지 심각도 단계에 해당한다: 1단계: 귀찮음 — API 소비자에게 마찰을 일으키지만 기능이 중단되지는 않는다. 일관되지 않은 명명 규칙이나 문서 누락 등을 생각해보라. 평균 수정 시간: 2-4시간. 평균 비즈니스 영향: 낮은 개발자 만족도 점수. 2단계: 비용 증가 — 대규모 리팩토링이 필요하거나 지속적인 유지 관리 부담을 초래한다. 불량한 버전 관리 전략이나 지나치게 결합된 엔드포인트를 생각해보라. 평균 수정 시간: 2-6주. 평균 비즈니스 영향: 기능 출시 지연, 지원 비용 증가. 3단계: 재앙 — 데이터 손실, 보안 침해 또는 완전한 서비스 중단을 초래할 수 있다. 데이터를 삭제하는 GET 엔드포인트나 인증 우회 취약점을 생각해보라. 평균 수정 시간: 1-3개월(복구 포함). 평균 비즈니스 영향: 6-7자리 수. 오늘 다루는 7가지 실수는 세 단계 모두에 걸쳐 있다. 일부는 규모에 따라 다룰 때까지 사소해 보인다. 다른 것은 분명히 위험하지만 놀라울 정도로 일반적이다. 이 실수들이 특히 끔찍한 이유는 종종 개발 중에 또는 초기 생산 배포 중에도 드러나지 않기 때문이다. 이들은 규모에 도달했을 때, API를 발전시켜야 할 때, 또는 외부 소비자가 예상치 못한 방식으로 엔드포인트를 사용할 때 나타난다.내가 말할 수 있는 이야기: 페이지 매김 재앙
내가 직접 목격한 최악의 API 디자인 실수 — 한 Series B 스타트업이 가장 큰 기업 거래를 잃게 만든 이야기다. 회사는 프로젝트 관리 API를 만들었다. 깔끔하고, 잘 문서화되어 있으며, 빠르다. 그들은 15년간의 프로젝트 데이터를 새로운 시스템으로 마이그레이션하고 싶어하는 Fortune 500기업과 파일럿 계약을 체결했다. 계약은 연간 230만 달러의 가치가 있었다. 마이그레이션 팀은 `/api/projects` 엔드포인트를 통해 데이터를 가져오기 시작했다. 500개의 프로젝트 샘플 데이터셋으로 테스트할 때 모든 것이 완벽하게 작동했다. 그런 다음 운영 데이터에 대해 실행했는데, 340,000개의 프로젝트가 있었다. 엔드포인트는 오프셋 기반 페이지 매김을 사용했다: `/api/projects?offset=0&limit=100`. 표준적인 내용이다. 하지만 대규모에서 오프셋 페이지 매김에는 치명적인 결함이 있다: 오프셋이 증가함에 따라 데이터베이스 성능이 기하급수적으로 저하된다. 기록 0-100을 가져오기? 빠르다. 기록 100,000-100,100을 가져오기? 데이터베이스는 100,000개의 기록을 스캔해야 스킵할 수 있다. 오프셋 300,000에 도달했을 때, 각 요청은 45초가 걸리고 타임아웃 되었다. 6시간 걸려야 할 마이그레이션이 3일이 지난 후에도 여전히 진행 중이었다. Fortune 500의 인프라 팀은 이것을 잠재적인 DDoS 공격으로 표시했다. 스타트업의 CEO는 그들의 CTO에게 전화를 걸어 "아니, 그들이 공격하는 것이 아니다 — 그들의 API가 잘못 설계된 것일 뿐이다"라는 설명을 해야 했다. 더 나쁜 점은, 이를 수정하는 데는 브레이킹 변화가 필요했다는 것이다. 그들은 커서 기반 페이지 매김으로 전환해야 했고, 이는 모든 클라이언트가 통합 코드를 업데이트해야 함을 의미했다. Fortune 500 기업은 떠났다. 파일럿 도중 브레이킹 변화가 필요한 API 위에 구축하는 것을 감수할 수 없었다. 6개월 후 Series C 펀딩 실사를 진행할 때 그들의 API를 검토했다. 페이지 매김 문제는 여전히 존재했다. 그들은 이제 40명의 유료 고객이 있었고, 모두 코드를 업데이트해야 할 것을 겁내서 이를 수정할 수 없었다. API 디자인 실수의 특성은 이런 것이다 — 굳어져 버린다. 존재하는 시간이 길수록 수정하기 어려워진다. 새로운 통합은 브레이킹 변화를 가져오지 못하게 만드는 또 다른 이유가 된다.데이터: 운영에서 실제로 무너지는 것
2019년 이후 제가 진행한 400개의 API 디자인 리뷰를 분석했다. 운영에서 실제로 문제를 일으키는 것은 다음과 같다:| 실수 카테고리 | 빈도 | 평균 발견 시간 | 평균 수정 시간 | 브레이킹 변화 필요? |
|---|---|---|---|---|
| 불량한 페이지 매김 전략 | 67% | 4-8개월 | 6-12주 | 예 (89%) |
| 일관되지 않은 오류 응답 | 82% | 2-3주 | 3-6주 | 아니오 |
| 누락된 속도 제한 | 43% | 1-2개월 | 2-4주 | 아니오 |
| 비Idempotent 작업 | 38% | 3-6개월 | 8-16주 | 예 (72%) |
| 과도한 가져오기/부족한 가져오기 | 91% | 1-3개월 | 4-8주 | 가끔 (45%) |
| 불량한 버전 관리 전략 | 56% | 6-12개월 | 12-24주 | 해당 없음 (향후 변화를 방지함) |
| 안전하지 않은 HTTP 메서드 | 12% | 1-4주 | 1-2주 | 예 (100%) |
왜 스마트 팀이 이러한 실수를 하는가
API 디자인에 대해 아무도 당신에게 말해주지 않는 것이 있다: 실수는 무능력에서 기인한 것이 아니다. 합리적으로 보이는 제한 속에서 내려진 결정에서 비롯된다."우리는 기본적으로 ORM이 제공하는 대로 오프셋 페이지 매김을 사용했습니다. 커서 기반 페이지 매김으로 전환하는 것은 스프린트에 2일을 추가했으며, 우리는 이미 일정에 뒤처져 있었습니다. 문제가 생기면 나중에 최적화할 수 있다고 생각했습니다." — 핀테크 스타트업의 엔지니어링 리드, 그들의 페이지 매김이 문제가 되기 3개월 전반복해서 보이는 패턴은: 팀은 신속하게 배송하기 위해 최적화하고, 장기적인 유지 관리 가능성은 고려하지 않는다. 당장에는 비즈니스 상 올바른 결정이지만, 문제는 "나중"이 결코 오지 않거나, 문제가 해결되는 것이 수십 개의 고객에게 영향을 미치는 브레이킹 변화를 요구할 때 온다는 것이다. 또 다른 일반적인 패턴은: 팀이 API를 소비자의 요구가 아닌 내부 데이터 모델을 기준으로 설계한다는 것이다. 데이터베이스에 47개의 열이 있는 `users` 테이블이 있어서 `/api/users` 엔드포인트가 모든 47개 필드를 반환한다고 가정해보라. 합리적인 것처럼 보이지 않는가? 하지만 모바일 앱에서는 그 필드 중 5개만 필요하고, 이제 수백만 대의 장치에 42개의 불필요한 필드를 셀룰러 네트워크를 통해 전송하고 있다.
"우리는 필드 필터링에 대해 생각했지만, 조기 최적화로 보였습니다. 우리의 엔드포인트는 테스트에서 충분히 빠른 속도를 보였습니다. 100명의 테스트 사용자가 있을 때 '충분히 빠름'이 100,000명의 실제 사용자와 함께 '용납할 수 없는 느림'이 된다는 것을 깨닫지 못했습니다." — SaaS 회사의 CTO, 그들의 모바일 앱 로드 시간이 4초인 이유를 설명하며세 번째 패턴은: 팀이 API 발전에 대해 생각하지 않는다. 그들은 버전 1을 설계하지만, 버전 2를 처리하는 방법에 대해서는 고려하지 않는다. URL이나 헤더에 버전 번호를 포함하지 않으며, 변경될 수 있는 필드와 안정적인 필드를 문서화하지 않는다. 그러고 나서 6개월 후에 브레이킹 변화를 만들어야 할 때, 기존 통합을 깨지 않고 깨끗하게 처리할 방법이 없다는 것을 깨닫게 된다. 그래서 나는 디자인 리뷰에서 항상 팀에게 묻는다: "이것을 변경해야 할 때는 어떻게 될까요?" 답변이 "그때 해결하겠습니다"라면, 당신은 고통을 불러일으키는 준비를 하고 있는 것이다.
"RESTful 순수성" 가정에 도전하기
여기서 인기 없는 의견이 있다: REST 원칙에 엄격하게 고수하는 것이 종종 API를 더 나쁘게 만든다, 더 좋게 만드는 것이 아니다. REST 순수론자들은 모든 리소스는 정확히 하나의 정식 URL을 가져야 하고, HTTP 메서드를 의미론적으로 사용해야 하며, API는 상태 비저장 및 캐시 가능해야 하고 Roy Fielding이 그의 논문에서 설명한 모든 다른 제약 조건을 따라야 한다고 말할 것이다. 실제로? 내가 검토한 최고의 API 중 일부는 그들의 사용 사례에 맞기 위해 REST 원칙을 위반한다. GitHub의 API를 살펴보라. 그들은 `/repos/{owner}/{repo}/commits`라는 엔드포인트가 있어 커밋을 반환한다. RESTful이지 않은가? 그러나 그들은 또한 `/search/commits`라는 엔드포인트가 있어... 커밋을 반환한다. 동일한 리소스, 다른 URL 구조. 왜? 커밋을 검색하는 것은 커밋을 나열하는 것과 근본적으로 다른 작업이기 때문이다. 정식 URL의 쿼리 매개변수에 검색을 억지로 집어넣으려 하면 더 나쁜 개발자 경험을 초래할 것이다. Stripe의 API를 고려해보라. 그들은 이론적으로 PUT이어야 할 비Idempotent 작업에 POST를 사용한다. 왜? POST가 HTTP 클라이언트에 더 널리 지원되고, 헤더의 Idempotent 키가 PUT과 동일한 보장을 제공하기 때문이다. 포인트는 REST가 나쁜 것이 아니라는 것이다 — REST는 지침 세트일 뿐 종교적 교리가 아니다. 목표는 직관적이고, 성능이 뛰어나며, 유지 관리하기 쉬운 API를 만드는 것이다. 때로는 REST 원칙을 따르는 것이 의미가 있다. 때로는 의도적으로 그것을 위반해야 할 수도 있다."우리는 우리의 대량 업데이트 엔드포인트가 PUT이 되어야 할지 POST가 되어야 할지 세 주 동안 논의했습니다. 돌이켜보면, 그 세 주 동안 더 나은 오류 메시지를 만드는 데 집중했어야 했습니다. API가 세부 사항 없이 '500 Internal Server Error'를 반환할 때 HTTP 메서드의 순수성은 관심도 없습니다." — 의료 회사의 API 아키텍트그 잘못된...