표지 준비 중

실무로 배우는 API 설계와 구현

전병선

리얼데브러닝 · 2026-10-31 출간 예정

ISBN 9791193469217 · 기술과학

정가 13,000원 · 전자책

출간 예정전자책국립중앙도서관 ISBN 서지정보 등록

출간되면 알려드릴게요

『실무로 배우는 API 설계와 구현』는 2026-10-31 출간 예정입니다. 출간되면 서점 판매 링크와 함께 이메일로 한 번 알려드립니다.

책 소개

API 를 설계하고 구현하는 책이다. 하나의 서비스를 도메인에서 설계해 REST · GraphQL · gRPC 라는 세 가지 계약으로 구현하고, 각 방식이 무엇을 맞바꿨는지 대조한다. 만드는 방법을 나열하는 데 그치지 않고, 주소를 어떻게 구성하고 실패를 어떻게 알리며 계약을 어떻게 바꿀 것인지를 판단하는 근거도 함께 제시한다.

코드는 설계의 결과이면서 그 설계를 검증하는 수단이다. 각 절은 후보를 나열하고 기준을 결정하고 트레이드오프를 따진다. 그 기준을 예제 서비스에 적용해 결론을 도출하고, 결론대로 구현해 의도한 대로 동작하는지 확인한다. 이 책의 코드는 실제로 실행되는 서비스다. 내린 결정이 코드의 어느 행에 나타나는지 함께 확인할 수 있다. 장 끝에는 그 장에서 내린 결정을 표로 남긴다.

전체는 4부로 이루어진다. 1부 REST 에서는 도메인 모델에서 리소스를 도출하고 메서드 · 상태 코드 · 요청과 응답 · 실패 · 목록 · 인증 · 진화를 설계한다. 이어서 그 서비스가 다른 서비스를 호출하는 측이 될 때 필요한 타임아웃 · 재시도 · 회로 · 관측을 설계한다. 2부 GraphQL 에서는 그 REST 서비스 위에 스키마와 리졸버를 추가해 클라이언트가 필요한 것만 받게 한다. 3부 gRPC 에서는 1부에서 만든 내부 호출을 계약 파일로 약속한 통신으로 바꾼다. 4부에서는 세 방식을 같은 기준으로 대조하고, 하나의 서비스가 세 계약을 함께 운영할 때 무엇을 결정해야 하는지 정리한다.

1부는 리소스를 데이터베이스 테이블 대신 도메인 모델에서 도출한다. 이를 위해 도메인 주도 설계(domain-driven design)의 집합체와 바운디드 컨텍스트를 API 설계의 재료로 사용하고, 그 경계가 URI · 필드 이름 · 한 요청의 범위로 어떻게 나타나는지 다룬다.

대상 독자는 스프링 부트로 API 를 만들어 봤지만 왜 그렇게 설계하는지 설명하기 어려운 개발자, 그리고 판단 근거를 마련하려는 개발자다. 자바와 스프링 부트 기초, HTTP 를 사용해 본 경험을 전제하고 REST 설계 · GraphQL · gRPC 는 전제하지 않는다.

출처: 국립중앙도서관 출판예정도서 등록 정보(출판사 제출)

요약

새 방식을 다루는 첫 장은 그 방식을 익히는 절을 앞에 두고, 그다음에 원리와 한계를 다룬다. 처음 접하는 독자에게는 그 절이 입문이 되고, 이미 써 본 독자에게는 원리와 한계를 읽기 전에 기본을 다시 확인하는 절이 된다.

설계 결론을 먼저 제시하지 않는다. 기준을 수립하고 그 기준을 예제에 적용해 결과를 도출한다. 따라서 같은 결론이라도 왜 그렇게 되는지를 함께 알 수 있다.

판단 기준은 1장에서 수립하는 예측 가능성, 일관성, 시맨틱스 세 가지다. 책 전체에서 이 기준을 사용한다. 앞의 두 가지는 방식과 무관하게 적용되고, 세 번째는 “그 방식의 명세가 규정한 의미를 지키는가”를 묻는다. 따라서 무엇이 그 명세인지만 부마다 달라진다. 그 명세는 1부에서는 HTTP 의 메서드와 상태 코드이고, 2부에서는 스키마와 에러 규약, 3부에서는 gRPC 의 상태 코드와 계약 진화 규칙이다.

각 장 끝에는 마무리를 두어 요점을 정리하고, 그 장에서 내린 결정을 표로 모으며, 자주 만나는 문제와 원인 · 해결을 정리하고, 과제 풀이를 둔다. 이 책에 실린 코드와 명령은 모두 실제로 실행해 검증한 것이다.

각 절은 본문 소절에서 그 절의 주제를 다루고 과제는 본문 뒤에 둔다. 실행할 프로젝트가 있는 절은 마지막에 ‘프로젝트 실행’ 소절을 두고, 그 소절에는 실행하는 명령, 그때 나온 출력, 그 출력을 읽는 방법을 둔다.

용어는 현업에서 통용되는 표준 용어를 쓰고, 처음 나올 때 괄호 안에 영어 원어를 함께 제시한다. 예를 들어 계약(contract)처럼 표기한다.

출처: 국립중앙도서관 ISBN 서지정보(출판사 제출)