BOOKSEEK READING GUIDE
API 설계 책 추천: 업무의 경계를 정하고 호출의 약속을 문서로 남기기
API 설계는 경로 이름을 정하는 일뿐 아니라 사용자 목적과 변경 가능한 계약을 정리하는 과정입니다. 『웹 API 설계 원칙』과 OpenAPI·스웨거 실습서를 비교해 업무 경계부터 읽을지 명세 작성부터 시작할지 고릅니다.
업무의 경계를 정하고 호출의 약속을 문서로 남기기
API를 구현할 수 있어도 어떤 기능을 하나의 경계로 묶어야 하는지, 명세에 무엇을 적어야 하는지는 별도의 고민입니다. 두 책은 같은 문제를 다른 지점에서 다룹니다. 『웹 API 설계 원칙』은 사용자 목적과 설계 과정을, OpenAPI·스웨거 책은 그 약속을 문서로 표현하고 도구로 검토하는 흐름을 읽는 데 맞습니다.
책을 고르기 전에 공부할 핵심
지금 해결하려는 문제를 먼저 정하고, 다음 개념을 기준으로 각 책의 설명 범위를 비교해 보세요.
데이터 목록보다 사용자 목표
테이블이나 화면의 항목을 API 목록으로 그대로 옮기기 전에 사용자가 어떤 일을 끝내려는지 적어 보세요. 같은 데이터라도 작업 목적에 따라 필요한 상호작용이 달라질 수 있습니다. 기능을 묶고 나누는 근거가 있어야 경로 이름에 관한 논의도 구체화됩니다.
요청과 응답은 함께 읽는 계약
API를 이용하는 쪽은 어떤 입력이 필요하고 어떤 결과나 실패를 받을 수 있는지 알아야 합니다. 스키마의 문법이 맞더라도 값의 의미와 필수 조건이 모호할 수 있습니다. 문서만 읽고 예시 요청을 만들 수 있는지 확인하면 설명의 빈틈을 찾기 좋습니다.
변경은 기존 사용자와의 문제
제공자가 작은 수정으로 생각하는 변경도 사용자의 코드에는 영향을 줄 수 있습니다. 필드나 응답 구조를 바꾸려면 어떤 계약을 바꾸는지, 기존 이용자는 무엇을 결정해야 하는지 살펴보세요. 버전과 폐기를 포함한 생애주기를 처음 설계의 질문에 넣는 이유입니다.
API의 목적과 경계를 먼저 정리하기
설계한 약속을 OpenAPI로 작성하고 검토하기
『OpenAPI와 스웨거를 활용한 실전 API 설계』는 요청·응답·스키마를 실제 명세로 표현할 일이 있는 독자에게 골랐습니다. 설계 우선 접근에서 문서화와 도구 활용, 테스트와 변경으로 이어집니다.
연습용 API 하나를 정해 명세만 보고 요청을 만들 수 있는지 확인해 보세요. 자동 생성된 문서가 있다는 사실과 사용자에게 필요한 설명이 충분하다는 사실은 구분해야 합니다. 어떤 부분을 도구가 확인하고 어떤 부분을 사람이 검토할지도 적어 볼 수 있습니다.
2024년 한국어 종이책이며 OpenAPI 3.0.x 범위를 다룹니다. 실제 프로젝트의 명세 버전과 도구 조건이 같은지는 별도 확인이 필요합니다.
선택 기준과 다음 독서 질문
무엇을 API로 나눌지부터 막힌다면 『웹 API 설계 원칙』이 먼저입니다. 경계는 어느 정도 정했지만 요청과 응답의 약속을 팀과 공유하기 어렵다면 OpenAPI·스웨거 책의 실습 범위가 더 가깝습니다.
다음 질문은 사용자가 이 API로 끝내려는 일을 한 문장으로 설명할 수 있는가입니다. 이어서 그 일을 문서만 읽고 수행할 수 있는지 확인해 보세요. 어느 단계에서 막히는지에 따라 필요한 독서가 달라집니다.
『웹 API 설계 원칙』은 구현 경험은 있지만 API를 나누는 근거가 불명확한 독자에게 골랐습니다. 요구사항과 사용자 목표에서 시작해 경계와 상호작용을 정하고 변경·버전·폐기까지 고려하는 범위를 다룹니다.
팀에서 같은 요구사항을 각자 설계한 뒤 경로 이름보다 책임을 나눈 이유를 비교해 보세요. 작게 나눌수록 좋다는 결론을 먼저 두기보다 어떤 작업을 지원하고 무엇이 함께 바뀌는지 질문하는 데 활용할 수 있습니다.
특정 프레임워크의 최신 구현 절차를 배우는 책보다는 설계 판단을 설명하는 책에 가깝습니다. 2023년 한국어판의 내용을 도구 지원 현황과 분리해 읽으면 좋습니다.