REST API Design Best Practices — txt1.ai

마커스 첸, 핀테크 및 의료 회사에서 14년 동안 확장 가능한 시스템을 구축한 수석 API 아키텍트

3년 전, 저는 한 스타트업이 API 디자인이 근본적으로 잘못되어 230만 달러의 엔지니어링 비용을 소모하는 모습을 보았습니다. 그들은 일관되지 않은 명명 규칙과 버전 관리 전략 없이 47개의 서로 다른 엔드포인트로 구성된 결제 처리 시스템을 구축했습니다. 그들의 가장 큰 고객을 위한 새로운 기능을 추가해야 할 때, 변경 사항은 도미노처럼 전체 시스템에 영향을 미쳤습니다. 6개월 후 리팩토링 끝에 그들은 가장 큰 고객을 잃고 40%의 엔지니어링 팀을 해고했습니다.

그 재난은 저에게 중요한 교훈을 주었습니다: API 디자인은 단순히 오늘날 작동하도록 하는 것이 아닙니다. 시스템과 세상 사이에 시간이 지나도 우아하게 발전할 수 있는 계약을 구축하는 것입니다. 수백만 개의 요청을 처리하고 개발자들이 실제로 사용하고 싶어하는 만큼 직관적으로 남아있는 것입니다. 연간 수십억 건의 거래를 처리하는 API를 설계한 10년 이상의 경험을 통해, 좋은 API와 훌륭한 API의 차이는 대부분의 팀이 간과하는 몇 가지 기본 원칙에 달려 있다는 것을 배웠습니다.

기초: REST를 유행어 너머 이해하기

2010년에 제 경력을 시작했을 때 REST는 이미 웹 API의 지배적인 아키텍처 스타일이었지만, 많은 개발자들이 이를 철학보다 체크리스트처럼 취급하는 경향이 있음을 알았습니다. REST는 표현 상태 전송(Representational State Transfer)의 약자로, 로이 필딩이 박사 논문에서 제시한 여섯 가지 핵심 제약 조건에 기반합니다. 그러나 실제로 중요한 것은: REST는 API 리소스를 명사로 취급하고, HTTP 메서드를 동사로 사용하며, 무상태성을 유지하는 것입니다.

무상태성 원칙만으로도 수많은 디버깅 시간을 절약할 수 있었습니다. 클라이언트에서 서버로의 모든 요청은 해당 요청을 이해하고 처리하는 데 필요한 모든 정보를 포함해야 합니다. 서버에 세션 상태가 없다는 의미입니다. 이는 API가 복잡한 세션 관리 없이 수평으로 확장할 수 있게 하며, 클러스터의 어느 서버든 모든 요청을 처리할 수 있습니다. 하루에 320만 건의 거래를 처리하는 의료 플랫폼을 위해 결제 API를 설계할 때 이 원칙 덕분에 애플리케이션 코드를 한 줄도 변경하지 않고 4대의 서버에서 피크 기간에 47대로 확장할 수 있었습니다.

하지만 REST는 교리가 아닙니다. 저는 팀들이 "진정 RESTful"인지에 대해 몇 주간 논쟁하며 시간을 낭비하는 것을 보았습니다. 그들이 집중해야 할 것은 일관성과 사용성입니다. 목표는 개발자가 직관적으로 이해할 수 있는 API를 만드는 것입니다. HTTP 메서드를 올바르게 사용하고, 리소스를 논리적으로 구성하며, 무상태성을 유지하고 있다면 당신은 90%의 길을 간 것입니다. 나머지 10%는 당신의 API를 사용하기 즐겁게 만들기 위한 실질적인 패턴에 관한 것입니다.

자원 명명: 직관적인 URL의 기술

URL 구조는 개발자가 처음 보는 것이며, 전체 API에 대한 기대를 설정합니다. 저는 간단한 규칙을 따릅니다: 리소스에는 명사를 사용하고, 복수형으로 유지하며, 명확한 부모-자식 관계가 있을 때는 계층적으로 조직합니다. 예를 들어, /api/v1/users/12345/orders/67890는 즉시 당신이 12345번 사용자에 속한 67890번 주문을 보고 있다는 것을 알려줍니다.

"최고의 API는 개발者가 문서를 읽기 전에 다음 엔드포인트를 예측할 수 있는 경우입니다. 그때 당신은 진정한 일관성을 달성했음을 알 수 있습니다."

대부분의 팀들이 잘못하는 부분은: URL에 동사를 섞는 것입니다. 저는 /api/getUser 또는 /api/createOrder와 같은 엔드포인트를 가진 API를 검토했습니다. 이는 중복적이며, HTTP 메서드가 이미 동사를 제공합니다. GET /api/users/12345는 GET /api/getUser/12345보다 더 명확하고 RESTful입니다. HTTP 메서드는 당신이 수행하고 있는 작업을 알려주고, URL은 당신이 어떤 리소스에 행동하고 있는지 알려줍니다.

일관성이 완벽성보다 더 중요합니다. 하나의 프로젝트에서 우리는 사용자 리소스에 대해 /users를 사용할지 /accounts를 사용할지 논쟁을 벌였습니다. 우리는 그 회의에서 3시간을 보냈습니다. 중요했던 것은 우리가 어떤 용어를 선택하는지가 아니라, 하나를 정하고 전체 API에서 일관되게 유지하는 것이었습니다. 우리는 우리의 결정을 문서화하고, 이를 API 스타일 가이드에 추가하고, 나아갔습니다. 그 일관성 덕분에 개발자들은 문서를 지속적으로 확인하지 않고도 엔드포인트 이름을 예측할 수 있었습니다.

중첩 리소스의 경우, 깊이를 최대 2~3단계로 제한합니다. 그 이상이 되면 URL이 다루기 어려워지고 관계가 불분명해집니다. /api/companies/123/departments/456/teams/789/members/012와 같은 구조를 작성하게 된다면, 당신은 너무 멀리 나아간 것입니다. 대신 팀을 최상위 리소스로 만들어 쿼리 매개변수를 사용하는 것을 고려하십시오: /api/teams/789/members?company=123&department=456. 이는 URL을 관리 가능하게 유지하면서도 리소스를 적절히 필터링하고 범위를 지정할 수 있도록 합니다.

HTTP 메서드: 적절한 도구 사용하기

HTTP는 다양한 메서드의 풍부한 어휘를 제공하지만, 많은 개발자들이 이를 지속적으로 잘못 사용하거나 GET과 POST에만 제한하는 것을 봅니다. 각 메서드의 의미를 이해하는 것은 직관적이고 캐시 가능한 API를 구축하는 데 도움이 되었습니다. GET은 리소스를 검색하며, 멱등성과 안전성을 가져야 합니다. 여러 번 호출해도 동일한 결과를 반환하며 부작용이 없습니다. POST는 새로운 리소스를 생성합니다. PUT은 전체 리소스를 교체합니다. PATCH는 리소스의 일부를 업데이트합니다. DELETE는 리소스를 제거합니다.

PUT과 POST의 멱등성은 안정성에 필수적입니다. 847개 매장을 가진 소매 체인을 위한 재고 관리 API를 구축할 때, 우리는 업데이트에 대해 PUT을 사용했습니다. 이는 멱등성 보장 때문이었습니다. 네트워크 문제로 요청이 두 번 전송되더라도, PUT은 우리가 실수로 중복 기록을 생성하거나 동일한 업데이트를 여러 번 적용하지 않도록 보장했습니다. 이 단일 결정은 운영 첫 해에 약 12,000건의 재고 불일치를 방지했습니다.

PATCH는 활용되지 않지만 매우 가치 있는 기능입니다. 클라이언트가 사소한 업데이트를 위해 전체 리소스 표현을 전송할 필요 없이, PATCH는 부분 업데이트를 허용합니다. 30개 필드를 가진 사용자 프로필을 업데이트 할 때, 이메일 주소만 변경하고 싶다면 왜 클라이언트에게 모든 30개 필드를 전송하게 해야 합니까? PATCH /api/users/12345에 본문으로 {"email": "[email protected]"}을 사용하는 것이 전체 리소스를 요구하는 것보다 더 효율적이고 오류 발생 가능성이 적습니다.

DELETE도 멱등성이 있어야 합니다. 이미 삭제된 리소스에 대해 DELETE를 호출하면 204 No Content 또는 404 Not Found를 반환해야 하며, 오류를 반환해서는 안 됩니다. 이는 재시도 로직을 더 간단하고 신뢰할 수 있게 만듭니다. DELETE가 리소스를 물리적으로 제거하지 않고 비활성 상태로 표시하는 소프트 삭제를 구현한 경험이 있으며, 이를 통해 감사 추적을 제공하고 복구가 가능하게 만들 수 있었습니다. 핵심은 동일 리소스에 대한 후속 DELETE 호출이 동일한 결과를 생성해야 한다는 것입니다. 즉, 클라이언트의 관점에서 리소스가 사라진 것입니다.

상태 코드: HTTP의 언어를 유창하게 사용하기