웹 API 설계 원칙

책의 기본 정보

출판사

에이콘출판

출간일

2023-12-28

분량

428쪽

ISBN

9791161758046

책의 내용과 읽을 거리

『웹 API 설계 원칙』은 어떤 경로와 메서드를 사용할지 정하기 전에 API가 누구의 어떤 일을 돕는지 묻는 책입니다. 업무 요구사항을 파악하고 API의 경계와 상호작용을 정하며, 이후의 변경과 운영을 생각하는 설계 과정을 다룹니다. 이미 요청과 응답을 구현해 보았지만 엔드포인트를 나누는 근거가 약하거나 팀마다 설계 기준이 달라 고민하는 개발자에게 맞습니다.

API를 설계할 때 데이터베이스의 테이블을 곧바로 외부 기능 목록으로 옮기면 사용자의 작업 흐름이 드러나지 않을 수 있습니다. 이 책은 설계의 출발점을 업무와 사용 목적에 두도록 읽을 수 있습니다. 구현할 기능을 나열하기 전에 누가 어떤 결과를 얻으려는지 문장으로 적어 보세요. 같은 데이터가 필요하더라도 사용자가 수행하는 일에 따라 API에서 묶을 행동과 경계가 달라질 수 있습니다.

설계 과정에서 경계를 나누는 일은 이름을 잘 붙이는 것보다 넓은 문제입니다. 어떤 기능들이 같은 목적을 위해 협력하는지, 서로 바뀌는 이유가 같은지 살펴보세요. 책의 API 구분과 마이크로서비스 관련 설명은 이러한 판단을 질문으로 만드는 데 활용할 수 있습니다. 단위가 작을수록 무조건 좋은 설계라고 생각하기보다 사용자의 작업과 팀의 책임이 잘 드러나는지 확인하는 편이 좋습니다.

요청과 응답의 상호작용을 읽을 때는 한 번의 호출만 보지 말고 사용자가 목표에 도달하기까지의 흐름을 살펴보세요. 필요한 정보를 얻기 위해 어떤 순서로 호출해야 하는지, 실패하면 어느 지점에서 다시 결정해야 하는지 적어 보는 활동을 권합니다. 이때 자신의 서비스 데이터를 사용하지 않아도 연습용 업무 시나리오로 검토할 수 있습니다. API를 이용하는 쪽의 관점이 설계 문서에 들어오는지 확인하는 방법입니다.

변경과 버전 관리, 폐기 정책을 다루는 범위는 API가 공개된 뒤의 문제와 연결됩니다. 제공하는 쪽에서 작은 수정으로 보아도 사용하는 쪽의 코드에는 다른 영향을 줄 수 있습니다. 바꾸고 싶은 항목 하나를 정한 뒤 기존 사용자에게 어떤 선택과 시간이 필요한지 적어 보세요. 책을 통해 처음 설계한 모습만 아니라 변화하는 계약을 어떻게 설명하고 검토할지 질문할 수 있습니다.

이 책을 팀에서 함께 읽는다면 같은 요구사항으로 설계안을 각자 작성한 뒤 차이를 비교하는 방식이 유용합니다. 경로의 취향을 먼저 논하기보다 어떤 사용자 목적을 기준으로 나누었는지부터 설명해 보세요. 책의 내용이 모든 조직에 동일한 구조를 정답으로 주는 것은 아닙니다. 선택의 근거와 바뀔 수 있는 조건을 기록하는 데 활용해야 실제 업무의 제약과 연결하기 쉽습니다.

소개하는 한국어 종이책은 2023년 출간본입니다. 특정 웹 프레임워크의 설치나 최신 도구 사용법보다 API 설계의 절차와 판단 기준을 읽는 목적에 적합합니다. OpenAPI 문서를 직접 작성하는 실습을 원하는 독자에게는 별도의 도구 중심 책과 차이가 있습니다. 이 책을 고를 때는 당장 구현 코드를 늘리는 일보다 요구사항과 경계를 설명해야 하는 상황인지 먼저 확인해 보세요.

이 책에서 공부할 수 있는 내용

업무 요구와 사용자 목표에서 API를 발견하고 경계를 정하는 과정, 상호작용과 변경·버전·폐기 정책을 공부할 수 있습니다. 활용 과제로는 하나의 업무 목표를 정해 필요한 호출 흐름을 그린 뒤, 각 API가 맡은 책임과 기존 사용자를 고려한 변경 조건을 적어 보기를 제안합니다.

설명 방식에서 눈여겨볼 특징

• 업무에서 출발하는 설계: 경로 이름보다 사용자의 목표와 요구사항을 먼저 살핍니다.
• API 경계의 판단: 기능을 나누는 이유를 책임과 상호작용의 관점에서 비교합니다.
• 설계 이후의 변화: 버전과 폐기 정책을 통해 기존 사용자의 영향을 고려합니다.
• 팀의 검토에 활용: 설계안의 모양보다 선택한 근거를 설명하는 질문을 만들 수 있습니다.
• 도구와 원칙의 구분: 특정 프레임워크 사용법보다 설계 과정에 집중하는 책입니다.

이런 독자에게 권합니다

HTTP API 구현 경험이 있고 요구사항을 API의 경계와 동작으로 옮겨야 하는 개발자·설계자에게 권합니다. API 호출법을 처음 배우거나 명세 파일 문법만 빠르게 익히려는 목적과는 다릅니다. 실제 설계 결정을 설명해야 할 때 활용할 수 있습니다.

작가 소개

제임스 히긴보텀은 애플리케이션과 API의 개발·배포, 소프트웨어 설계 경험을 가진 저자입니다. 출판사 소개에는 조직의 제품·업무·기술 요구를 연결하는 컨설팅과 API 설계 워크숍 이력이 실려 있습니다.

이 책과 함께 읽는 주제

• API 설계 책 추천: 업무의 경계를 정하고 호출의 약속을 문서로 남기기
• 백엔드 개발 입문 책 추천: 전체 구조에서 첫 API까지