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

드럼 키트에 대한 얘기부터 시작해보자. 2019년 여름, 친구 중 한 명이 전자 드럼을 통해 나를 드러밍의 세계로 끌어들였고, 나는 곧 이에 푹 빠졌다. 실제로 드럼을 연주하기도 했지만, 그보다 더 많은 공을 들인 것은 MIDI SysEx 명령어를 다루는 코드를 작성해 드럼 키트의 설정에 상호작용할 수 있게 하는 작업이었다.

신종 코로나 팬데믹이 들이닥친 다음, 내 관심사는 다니던 교회로 옮겨갔다. 원격으로 예배를 드리든 추후에 다시 대면 예배로 돌아가든, 예배 중 음악과 영상을 어떻게 다룰지 고려할 필요가 있었던 것이다. 이를 위해 VISCA, NDI, OSC 같은 (카메라 및 오디오 믹서 관련) 프로토콜과 더불어 줌(Zoom), VLC, 파워포인트(PowerPoint), 스팀 덱(Stream Deck) 등을 활용한 소프트웨어 지향 통합에 치중했다.

이러한 프로젝트는 비즈니스 로직이 큰 비중을 차지하지 않는다. 대부분의 코드는 통합에 관련된 내용이며, 당혹감과 성취감을 동시에 불러일으킨다. 당혹스러움을 느끼는 이유는, 프로토콜의 문서화가 명확하게 되지 않았거나 실제 사용 목적에 맞게 디자인되지 않았거나 그냥 일관성이 없기 때문이다. 성취를 느끼는 이유는, 통합에 관한 부분을 해결하기만 하면 거인들의 어깨 위에 서서 유용한 앱을 매우 쉽게 만들어낼 수 있기 때문이다.

앞에서 언급한 지난 몇 년 동안의 경험은 주로 로컬 통합에 치중된 것이지만, 웹 API에서도 동일한 당혹감과 성취감을 느낄 수 있다. 새로운 웹 API를 고를 때마다 거치는 감정 곡선은 흥분, 당혹감, 짜증, 순응, 그리고 끝으로 꺼림칙한 평온함으로 요약할 수 있다. 강력한 API가 무엇인지를 완전히 이해한다는 것은 어떤 곡이든 연주할 준비가 돼 있는 지휘자가 거대한 오케스트라 앞에 서 있을 때의 기분과 유사하다. 바이올린 파트가 끝까지 한 음만 연주한다든지, 금관 섹션을 지휘할 때 별다른 이유 없이 다른 색의 지휘봉을 사용해야 한다든지 할 수 있기는 하지만 말이다.

이 책이 뭔가를 바꾸지는 못한다. 이건 책일 뿐이니까. 그러나 어떤 독자가 이 책을 읽고 그 내용을 따른다면 API 사용자의 경험을 바꿀 수 있다. 수많은 사람이 이 책을 읽고 그 내용을 따른다면 우리 모두 훨씬 일관적이고 덜 당혹스러운 웹 API 경험을 만들어나갈 수 있다.

이 책은 단지 내용이 훌륭한 것에서 그치지 않는다. JJ가 다루고 있는 모든 주제는 사실 어떤 팀에서든 올바른 결정을 내릴 수 있는 것들이다(물론 누군가는 이 책에서 다루는 코너 케이스를 놓칠 수도 있을 것이다). 아마도 특정 상황에서는 이 책에서 추천하는 방식보다도 더 적합한 결정을 내릴 것이다. 책에서는 어쩔 수 없이 제한된 요구 조건을 다룰 수밖에 없기 때문이다. 이런 식의 접근을 통해 내리는 여러 결정은 지엽적인 관점에서는 최적의 선택이지만, 큰 그림에서 보면 매우 파편화된 양상을 보인다. 때문에 같은 회사 내의 API라도 다른 여러 접근법을 취해야 할 수도 있다.

이 책은 각각의 주어진 문제에서가 아니라 다양한 API 디자인 영역에 걸쳐 일관된 접근법을 보여준다. API 디자이너에게 이렇게 깊이 있게 고민할 수 있는 기회가 주어지기란 쉽지 않다. 나는 너무나 운 좋게도 JJ 같은 사람들(특히 루크 스네링거(Luke Sneeringer)를 포함한)과 함께 일하며 이 책에서 다룬 여러 주제를 논의할 수 있었다. 구글이 API 디자인을 위해 지원해 준 덕분에 이 책과 API 시스템(https://aip.dev)을 통해 많은 개발자가 도움을 얻을 수 있게 됐다 해도 과언이 아니다.

그러나 이 책이 갖고 있는 훌륭한 가치와 별개로, 이 책을 읽는다고 훌륭한 API를 손쉽게 디자인할 수 있다는 것은 아니다. 다만 API를 디자인함에 있어 따라오게 되는 많은 복잡한 문제를 해결해서, 만들고자 하는 API에 존재하는 나름의 문제에 집중할 수 있게 해준다. 물론 계속 생각하고 고민해야 하겠지만, 그렇게 해야만 API가 잘 작동할 것이란 확신을 가져야 한다. 물론 API 사용자들이 당신에게 직접 감사의 뜻을 표하지는 않을 것이며, 많은 경우 API를 잘 디자인하려면 수많은 노력이 필요하다. 하지만 어찌됐든 API 사용자들이 당황스러운 상황을 마주하지 않는다면 얼마나 다행스러운 일이겠는가.

이 책을 통해 당신의 API가 누군가에게 거인의 어깨 역할을 할 수 있기를 희망한다.

- 존 스킷(Jon Skeet),
구글의 스태프 데브렐 엔지니어(Staff Developer Relations Engineer, Google)

웹 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 요청을 디지털 서명함으로써 근원과 무결성을 입증 가능하게 하며, 이후 부인될 가능성을 방지하는 방식을 소개한다.

JJ 지웍스(JJ GEEWAX)

구글에서 소프트웨어 엔지니어로 일했으며, 실시간 결제 시스템, 클라우드 인프라 스트럭처, API 디자인을 주 업무로 삼고 있다. 『실습으로 완성하는 구글 클라우드 플랫폼 인 액션』(제이펍, 2019)의 저자이며, 구글에서 시작해 업계 전체에 걸친 API 디자인 표준 협업체인 API.dev를 공동으로 창설했다. 싱가포르에서 아내인 카엘(Ka-el), 아들 루카(Luca)와 함께 살고 있다.

학교에서 배우는 컴퓨터 과학은 마치 물리 법칙을 배우는 것과 같은 방식으로 이뤄진다. 빅O 표기법을 사용해 런타임과 공간 복잡성을 분석하고, 여러 정렬 알고리듬이 어떻게 작동하는지 배우고, 바이너리 트리를 순회하는 다양한 방법을 익힌다.
나는 앞으로도 이런 식으로 과학적이고 수학적으로 일하게 될 것이라 여겼다. 그러나 전혀 그렇지 않은 현실을 마주하고 엄청나게 놀랐다.

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

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

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

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

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

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

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

전성빈

기계공학과에서 광공학과 이미지 처리를 세부 전공으로 박사학위를 받았다. 지식의 시각화와 구조화에 꾸준한 관심을 기울이고 있다. 에이콘출판사에서 출간한 『컴퓨터 비전 5/e』(2022), 『파이썬 네트워킹 마스터 2/e』(2019), 『HLSL 프로그래밍』(2016) 등을 번역했다.

저자가 주도적으로 참여했던 aip.dev 사이트 소개글에서처럼 API를 디자인한다는 것은 결국 어떤 결정을 내리는 것입니다. 복잡한 기능을 어떻게 쉽고 간단하게 사용할 수 있도록 추상화해야 할까? 어느 수준까지 인터페이스를 바깥에 열어야 할까? 편리성과 유연함과 보안 간의 트레이드오프를 어떻게 따져야 할까? 혹은 지금 내린 이 결정을 나중에 바꿔야 할 수도 있을까? 누군가가 만든 API를 사용하면서 그들이 매 순간 마주했던 고민을 어렴풋이나마 가늠할 수 있었습니다.

이 책은 웹 API라는 기존의 전통적인 애플리케이션과 다른 성격을 갖는 API를 우리가 어떻게 다뤄야 할지를 기초부터 시작해 그 실마리를 제공합니다. 오랜 경력과 실무 경험을 녹여냈기 때문에, 그리고 시간이 지나 기술이 발전해도 크게 변하지 않을 디자인 패턴들을 추려냈기 때문에 곁에 두고 막힐 때마다 한 번씩 꺼내보면서 많은 도움을 받을 수 있는 책이라고 믿습니다.

이 책이 독자에게 많은 도움을 줄 수 있도록 나름 최선을 다해 번역했으나 부족한 부분이 있을 수 있습니다. 어색한 부분이나 더 적절한 제안이 있다면 이메일 등으로 피드백 주시기를 부탁드립니다.