API 설계로 고민하는 모든 분께
복잡한 웹 API 세계의 길잡이가 되어 줄 단 하나의 책!

『웹 개발자를 위한 API 디자인 패턴』, 드디어 출간!

개발자라면 누구나 경험해봤을 것이다. 새로운 웹 API를 마주할 때마다 반복되는 감정의 롤러코스터를. 흥분, 당혹감, 짜증, 순응, 그리고 끝으로 꺼림칙한 평온함까지. 이 모든 것은 단순한 CRUD 메서드로는 해결되지 않는 세계다.

『웹 개발자를 위한 API 디자인 패턴』은 이 복잡하고 중요한 세계를 체계적으로, 실용적으로 풀어낸 필독서다. 구글 출신의 API 디자인 전문가 JJ 지웍스가 실무 경험을 바탕으로 다양한 웹 API 설계의 핵심 패턴을 정리한 이 책은, 난해한 개념을 현실적인 예제와 연계하여 설명했으며, 이론적 접근과 실무적 해결책을 조화롭게 결합하여 개발자들로부터 높은 평가를 받았다.

이 책을 통해 개발자는 리소스 식별부터 보안 구현까지 검증된 패턴을 익히고, 팀 내 일관된 API 설계 원칙을 세우며, 구글 수준의 전문 노하우와 체계적 의사결정 프레임워크를 바탕으로 TypeScript 기반의 실제 구현 가능한 코드까지 모두 얻을 수 있을 것이다.

1. "일관성"을 확보하라 ? API 설계 혼돈에서 벗어나는 핵심

API 설계에서 가장 큰 문제는 일관성의 부재다. 같은 팀, 같은 회사에서 만든 API조차 서로 다른 명명 규칙, 다른 에러 처리 방식, 다른 데이터 구조를 사용하며 개발자들을 혼란에 빠뜨린다. 『웹 개발자를 위한 API 디자인 패턴』은 이름 붙이기부터 리소스 계층 구조, 데이터 타입과 기본값까지 API 설계의 모든 요소에 일관된 원칙을 제시한다. RESTful API든 RPC든, 소규모 서비스든 대규모 플랫폼이든 반드시 일관성 있는 설계 패턴을 따라야만 한다. 이 책은 임시방편적인 API 설계를 넘어서 실제 확장 가능한 'API 설계' 전쟁이 어떻게 가능한지 안내해 줄 것이다.

2. 실전에 강해져라 ? 패턴을 "실제 코드"로 바꾸는 방법

이 책은 단순한 설계 원칙을 넘어, API 개발 과정에서 마주하는 모든 실무적 문제를 구체적인 패턴으로 해결하는 방법과 노하우를 제공한다. 또한 TypeScript 중심의 명확한 코드 예제, 체계적인 검증 절차, 리소스 관계와 보안 구현에 대한 단계별 접근법으로 실질적인 문제 해결 실력까지 갖추게 해준다. API를 제대로 설계하고 싶다면, 단순히 기능만 구현하는 차원을 넘어 확장 가능하고 유지보수 가능한 구조를 만드는 방법을 이 책에서 배울 수 있다. 게다가 구글의 실제 사례와 폭넓은 패턴 예제를 추가해, 책을 읽는 누구나 '내 프로젝트에 바로 적용할 수 있다'는 자신감을 안겨줄 것이다.

3. 설계가 전략이 되는 전쟁 ? 임시방편을 넘어 '확장 가능한 아키텍처'에 집중하라

이 책은 'API 설계를 전략으로, 그리고 실질적인 비즈니스 가치로 연결해주는 것'에 진심을 다한다. 또한 설계 결과를 실제 서비스 확장·팀 협업·장기 유지보수 정책에 녹여낼 수 있는 실전적 접근법을 제시한다. 이 책은 단순 기능 구현을 뛰어넘어, 전략적으로 리소스 모델링, 버전 관리, 보안 정책까지 실제로 적용하는 방법을 알려주며, 이에 더해 장기 실행 작업과 배치 처리, 그리고 복잡한 데이터 관계를 현명하게 다루는 노하우까지 제공한다. API가 곧 비즈니스 성공의 핵심 인프라임을 아는 이들에게 강력 추천하고 싶은 실전형 무기다.

API 설계라는 피할 수 없는 난제를 체계적인 패턴과 실전 전략으로 돌파하고 싶은 개발자라면, 지금 이 책을 선택하길 바란다.

웹 API, 특히 대중에 공개할 API를 만들고 있거나 만들 예정인 모든 독자를 대상으로 하는 책이다. 직렬화 포맷(예: JSON, 구글 프로토콜 버퍼, Apache Thrift)이나 일반적인 스토리지 패러다임(예: 관계형 데이터베이스 스키마)에 익숙하다면 도움이 되겠지만, 필수적인 것은 아니다. 또한 HTTP 및 관련한 여러 메서드(예: GET, POST)는 이 책 전반에 걸쳐 예제 내의 전송 방식으로 자주 등장하기 때문에 알고 있는 것이 이해에 더 유리하다. API를 디자인하면서 문제를 마주하고 “어딘가 이 문제를 해결하는 방법이 있을 텐데”라고 생각해 본 적이 있다면 이 책은 당신을 위한 것이다.

◈ 이 책의 구성 ◈

이 책은 6개의 부로 구성돼 있다. 처음 2개의 부는 API 디자인에 관한 좀 더 일반적인 주제를, 나머지 4개의 부는 각 디자인 패턴에 대한 세부를 다룬다.

1부, 서론에서는 책의 나머지 부분에 관한 개괄과, 웹 API와 나중에 웹 API에 적용할 디자인 패턴의 정의 및 평가 프레임워크를 살펴본다.

● 1장, API 소개에서는 API가 무엇을 뜻하는지와 왜 API가 중요한지를 다룬다. 아울러 API가 얼마나 좋은지를 평가할 수 있는 프레임워크를 제시한다.
● 2장, API 디자인 패턴 소개에서는 1장에서 더 나아가, API에 디자인 패턴을 적용하는 방법과 왜 디자인 패턴이 유용한지를 다룬다. 이를 위해 API 디자인 패턴의 내부 구조를 분석하고, 디자인 패턴을 사용해 API를 개선하는 간단한 예를 보여준다.

2부, 디자인 원칙에서는 1부의 내용을 기반으로 해서 API를 제작할 때 고려해야 할 몇 가지 일반적인 디자인 원칙을 다룬다.

● 3장, 이름 붙이기에서는 API에서 이름을 붙여야 하는 여러 가지 구성 요소를 살펴보고, 이름을 선택할 때 무엇을 고려해야 할지 다룬다. 아울러 이름 붙이기가 단순히 피상적인 차원을 떠나 높은 중요성을 갖는 이유를 설명한다.
● 4장, 리소스 범위와 계층에서는 여러 리소스가 서로 관계를 갖는, 좀 더 규모가 큰 API를 다룬다. 리소스와 그 관계를 어떻게 결정해야 할지에 관한 몇 가지 질문을 던진 후 이 과정에서 피해야 할 점들을 예를 통해 살펴본다.
● 5장, 데이터 타입과 기본값에서는 API 내의 다양한 데이터 타입과 그 기본값을 사용하는 방법을 다룬다. 가장 흔히 쓰이는 문자열이나 숫자 값뿐만 아니라, 맵이나 리스트 등의 복잡한 타입도 함께 살펴본다.

3부, 기초 패턴부터는 본격적으로 디자인 패턴을 살펴본다. 우선 대부분의 API에 적용해야 하는 기초 패턴부터 시작한다.

● 6장, 리소스 식별에서는 API 사용자가 리소스를 식별하는 방법을 알아본다. 묘석화(tombstoning), 문자열 세트, 인코딩 등 로우레벨 세부 사항까지 모두 살펴보며, 체크섬을 통해 ID가 누락된 것인지 유효하지 않은지 구분하는 방법도 다룬다.
● 7장, 표준 메서드에서는 웹 API의 여러 표준 메서드(get, list, create, update, delete)가 작동하는 방법을 알아본다. 또한 각 표준 메서드가 모든 리소스에 대해 동일한 방식으로 작동해야 하며, 각 리소스마다 그 특성에 따라 차이를 보이면 안 되는 이유를 설명한다.
● 8장, 부분 업데이트와 부분 취득에서는 표준 메서드 중 2가지(get, update)를 확장해서 사용자가 리소스 중 일부에 대해서만 상호작용하는 방법을 알아본다.
아울러 이 방법이 (사용자와 API 양측에) 왜 필요하고 유용한지, 그리고 기존 시스템에 대한 개입을 최소화하면서 이 기능을 구현하려면 어떻게 해야 하는지 알아본다.
● 9장, 사용자 메서드에서는 기존 표준 메서드 대신 API 내에서 원하는 기능을 사용자 메서드로 구현하는 방법을 알아본다. 특히 사용자 메서드가 가능한(혹은 가능하지 않은) 상황이 언제인지와, API 내에서 가능 여부를 어떻게 결정해야 하는지 살펴본다.
● 10장, 장기 실행 작업에서는 API 메서드가 즉각적으로 동작하면 안 되는 특수한 상황과, 이 상황을 편리하게 다룰 수 있는 장기 실행 작업(LRO, Long-Running Operation)을 알아본다. LRO가 어떻게 작동하는지, LRO가 지원하는 메서드(일시정지, 재개, 취소)가 어떻게 이뤄지는지도 살펴본다.
● 11장, 재수행 가능 작업에서는 어떤 작업을 반복해서 실행하는, 마치 웹 API상에서 cron 작업을 수행하는 개념을 다룬다. 익스큐션(Execution) 리소스를 사용하는 방법과, 이를 스케줄에 따라 또는 원하는 시점에 실행하는 방법을 알아본다.

4부, 리소스 관계에서는 리소스와 리소스 간의 관계에 집중한다. 4장의 내용을 좀 더 상세히 설명하는 셈이다.

● 12장, 싱글톤 서브리소스에서는 작은 크기의, 관계를 이루면서 격리된 데이터를 싱글톤 서브리소스로 분리하는 방법을 설명한다. 특히 이 방식을 적용하는 것이 적절하거나 적절하지 않은 경우가 언제인지 살펴본다.
● 13장, 교차 참조에서는 웹 API에서 리소스가 다른 리소스의 참조를 참조 포인터나 인라인 값으로 저장하는 방법을 개괄한다. 아울러 캐스케이드 삭제나 시간에 따라 변경된 데이터를 업데이트하는 등의 특수한 상황에 대응하는 방법도 살펴본다.
● 14장, 연관 리소스에서는 리소스 간의 일대일 관계를 확장해서 연관 리소스를 통해 다대다 관계를 나타내는 방법을 설명한다. 또한 이들 관계를 메타데이터로 어떻게 저장할 수 있을지 다룬다.
● 15장, add 및 remove 사용자 메서드에서는 다대다 관계를 다룸에 있어 연관 리소스 대신 add 및 remove 등의 메서드로 간편하게 수행하는 방법을 다룬다. 아울러 이들 메서드의 트레이드오프와, 왜 이 방식이 항상 잘 들어맞는 것은 아닌지 살펴본다.
● 16장, 다형성에서는 다형성, 즉 변수가 다양한 타입에 대응할 수 있게 하는 개념을 살펴본다. API 리소스 내의 다형성 필드를 다루는 방법과, 다형성 메서드 사용을 피해야 하는 이유를 설명한다.

5부, 선택적 작업에서는 단일 API 리소스의 상호작용을 넘어서 전체 리소스 컬렉션에서의 상호작용에 대한 디자인 패턴을 살펴본다.

● 17장, 복사와 이동에서는 API 내에서 리소스를 복사하거나 이동하는 방법을 설명한다. 외부 데이터를 다루거나, 서로 다른 부모 리소스에서 메타데이터를 상속하거나, 자식 리소스를 다루는 방법 등 다소 복잡한 문제를 해결한다.
● 18장, 배치 작업에서는 표준 메서드(get, create, update, delete)를 단일 리소스가 아닌 컬렉션에 동시에 작업하는 방법을 알아본다. 또한 그 작업 결과를 반환받는 방법이나 부분적 실패를 다루는 방법 등 까다로운 문제도 살펴본다.
● 19장, 기준 기반 삭제에서는 18장의 배치 delete 메서드를 확장해서 특정 리소스가 아닌 필터 조건에 맞는 모든 리소스를 제거하는 방법을 다룬다. 또한 일관성 문제를 해결하는 방법과, 의도치 않은 데이터 파괴를 피하는 규범을 살펴본다.
● 20장, 익명 기록에서는 직접적으로 지시할 수 없는 비리소스 데이터를 입력하는 방법을 자세히 들여다본다. 익명으로 데이터를 작성하는 방식과, 이러한 익명 데이터 입력의 일관성과 API에 적합한지를 판단하는 트레이드오프를 살펴본다.
● 21장, 페이징에서는 페이징을 통해 큰 규모의 데이터 세트를, 불투명 토큰을 사용해 오고가는 식으로 브라우징하는 방법을 설명한다. 아울러 커다란 단일 리소스 내에서도 페이징을 구현하는 방법을 살펴본다.
● 22장, 필터링에서는 필터 기준을 적용해 리소스 목록을 나타내는 방법과, API에서 필터를 가장 잘 표현하는 방법을 다룬다. 이 내용은 19장에서 다룬 주제와 직접적으로 연관된다.
● 23장, 가져오기와 내보내기에서는 리소스를 API 안팎으로 가져오고 내보내는 방법을 다룬다. 아울러 이들 동작이 백업 및 복원과 어떤 맥락의 차이를 보이는지도 살펴본다.

6부, 안전과 보안에서는 다소 지루할 수도 있는 주제인, API의 안전성과 보안에 관해 살펴본다. API를 공격자로부터 안전할 수 있게 하는 방법과 더불어, 사용자 자신의 실수로부터 보호하는 API 메서드를 제시한다.

● 24장, 버전 작성과 호환성에서는 버전 작성과 다른 버전 간의 호환성이 갖는 의미를 다룬다. 호환성을 일종의 스펙트럼 개념으로 접근해서 API 전체에 걸쳐 일관적으로 호환성 정책을 정의하는 것의 중요성을 알아본다.
● 25장, 논리 삭제에서는 사용자 자신의 실수를 보호할 수 있는 패턴(논리 삭제)을 제시한다. 즉, 리소스를 보이지 않게 제거하되, 완전히 시스템에서는 삭제되지 않게 한다.
● 26장, 요청 중복 방지에서는 요청 식별자를 사용해 시스템에서의 중복 동작 방지를 시도한다. 이 과정에서 요청 ID를 사용하는 것의 어려움과, 큰 스케일의 시스템에서 ID가 제대로 다뤄지는지 확인하는 알고리듬을 살펴본다.
● 27장, 요청 검증에서는 요청을 검증해 사용자가 실제 작업을 실행하지 않고도 동작 결과를 미리 보기 할 수 있는 방법을 다룬다. 아울러 실제 요청과 검증 요청 각각의 부수 효과 등 좀 더 복잡한 문제를 살펴본다.
● 28장, 리소스 리비전에서는 시간에 따른 변화를 추적하는 리소스 리비전을 소개한다. 이전 리비전을 복원하는 등의 기본적인 작업과, 계층 내의 자식 리소스에 리비전을 적용하는 등의 고급 주제를 살펴본다.
● 29장, 요청 재시도에서는 사용자에게 API 요청 재시도가 필요함을 알리는 패턴을 소개한다. 아울러 여러 종류의 HTTP 응답 코드 및 각각이 재시도에 안전한지의 여부를 제시한다.
● 30장, 요청 인증에서는 각 요청의 인증과 API가 사용자를 인증할 때 고려해야 할 여러 보안 기준을 살펴본다. API 요청을 디지털 서명함으로써 근원과 무결성을 입증 가능하게 하며, 이후 부인될 가능성을 방지하는 방식을 소개한다.

◈ 지은이의 말 ◈

학교에서 배우는 컴퓨터 과학은 마치 물리 법칙을 배우는 것과 같은 방식으로 이뤄진다. 빅O 표기법을 사용해 런타임과 공간 복잡성을 분석하고, 여러 정렬 알고리듬이 어떻게 작동하는지 배우고, 바이너리 트리를 순회하는 다양한 방법을 익힌다.

나는 앞으로도 이런 식으로 과학적이고 수학적으로 일하게 될 것이라 여겼다. 그러나 전혀 그렇지 않은 현실을 마주하고 엄청나게 놀랐다.

내 업무는 수학이나 알고리듬을 활용하기보다는 디자인이나 구조, 혹은 뭔가 미적인 것을 다루는 것에 더 가깝다. 어떤 정렬 알고리듬을 사용할 것인지 생각할 필요는 전혀 없다. 이를 위한 라이브러리가 (예를 들어 array.sort() 같은 형태로) 준비돼 있기 때문이다. 그러나 언젠가 클래스와 각 클래스 내의 함수와 각 함수에 따르는 매개변수에 대해 깊이 고민해야 하는 상황이 왔을 때 나는 이 일이 생각보다 훨씬 어렵다는 것을 알게 됐다.

현실에서는 아무리 완벽하게 최적화된 코드라도 잘 디자인된 코드만 못하다. 웹 API에서는 특히 더 그렇다. 훨씬 더 다양한 사용자를 대상으로 하며, 훨씬 광범위한 용례가 존재하기 때문이다.

그런데 ‘잘 디자인된’ 소프트웨어는 어떤 뜻일까? ‘잘 디자인된 웹 API’는 무엇일까?

나는 이 질문의 답을 찾기 위해 오랫동안 리소스를 긁어모았다. 어떤 주제는 최근 동향을 다루는 블로그 포스트에서 해답을 구할 수 있었다. 어떤 주제는 스택 오버플로(Stack Overflow)에 올라온 답변을 통해 올바른 방향으로 나아갈 수 있었다. 그러나 대부분은 질문에 대한 답을 찾기에 충분한 자료가 존재하지 않았다. 결국 남은 방법은 직장 동료가 거슬려 하지 않기를 바라며 스스로 답을 만들어가는 것뿐이었다.

여러 해 동안 이 작업을 계속한 끝에(나는 작업을 기록한 노트 표지에 ‘끔찍한 API 문제들’이란 제목을 적어놨다) 마침내 지금까지 모아온 검증된 모든 정보를 정리하기로 마음먹었다. 우선 구글을 위한 규칙으로서 루크 스네링거(Luke Sneeringer)와 함께 이를 집대성했다. 이 작업물은 이후 AIP.dev에 공개됐다. 그러나 이 규칙은 일종의 법전과 같은 형태로 구성돼 있다. 여러분은 이것을 해야 하고, 저것은 하면 안 된다. 그러나 왜 그래야 하는지는 말하지 않는다. 많은 탐구와 고민 끝에, 규칙에 덧붙여 그 이유를 설명하는 이 책이 세상에 나오게 됐다.

이 책이 온 세상의 API 디자인 문제를 해결하는 만능 도구가 된다면 좋겠지만 아쉽게도 그러지는 못할 것이다. 이유는 단순한데, 건축물과 마찬가지로 디자인은 결국 어떤 의견에 관한 문제이기 때문이다. 독자가 이 책에서 소개하는 지침이 아름답고 우아하다고 생각했다면 앞으로의 모든 프로젝트에 이를 반영할 것이다. 그러나 누군가는 이 책에 나오는 디자인이 진저리나게 싫고 제약이 심하다고 생각해서 오히려 웹 API를 만드는 데 있어 반면교사로 삼을 수도 있다. 모두를 만족할 수는 없을 것이다. 이 책의 유일한 목표는 실무에서 검증된 지침과 그 지침에 대한 논리적인 설명을 제공하는 것이다.

이 책을 따를 것인지, 피할 것인지는 독자의 선택이다. 다만 이 책에서 다룬 내용들을 기반으로 많은 의견을 나누고 흥미롭지만 복잡하고 난해한 API 디자인의 세계에서 더 많은 작업이 이뤄지기를 바랄 뿐이다.