2023년 12월 28일 출간 | ISBN : 1161758046 | 428쪽

저자 : 제임스 히긴보텀 25년 이상의 앱 및 API 개발 및 배포 경험을 가진 소프트웨어 개발자이자 설계자다. 기업의 디지털 혁신 여정을 안내하고 제품 기반 사고를 통해 비즈니스와 기술 간의 조정을 보장해 우수한 고객 경험을 제공한다. 팀 및 조직과 협력해 비즈니스, 제품 및 기술 전략을 좀 더 구성 가능한 모듈식 엔터프라이즈 플랫폼으로 조정하는 데 도움을 준다. 또한 기능 간 팀이 ADDR 프로세스를 사용해 API 설계 우선 접근 방식을 적용하는 데 도움이 되는 워크숍을 제공한다. 업계 경험으로는 은행, 상업 보험, 서비스, 여행 그리고 말 그대로 항공사를 착공하게 도운 항공 산업이 포함된다. 역자 : 정영민 2010년 삼성전자에서 커리어를 시작해 삼성전자의 삼성페이(Samsung Pay), 빅스비(Bixby) 등 글로벌 스케일 서비스를 클라우드(Cloud) 환경 위에서 설계하고 운영하며, 대규모 서비스의 모니터링 전략, 운영 절차들을 수립했다. 현재는 앞선 경험을 기반으로 AWS에서 엔터프라이즈 고객이 높은 수준의 아키텍처 설계를 선택하고 AWS 서비스를 통해 사용 사례를 구축할 수 있게 지원하는 업무를 담당하고 있다. 역자 : 이혁 2011년 모바일의 물결과 함께 안드로이드 앱 개발자로 사회생활을 시작했다. 내가 만든 것을 UI를 통해 즉시 볼 수 있고, 다양한 사람들이 사용할 수 있다는 것이 굉장히 큰 매력이었다. 이후 삼성전자의 다양한 글로벌 스케일 서비스에서 DBA로의 삶을 살며 지구상의 다양한 디바이스가 24시간 인터넷을 통해 만들어내는 트래픽을 경험할 수 있었다. 현재는 클라우드의 물결과 함께 AWS에서 솔루션즈 아키텍트(SA, Solutions Architects) 역할을 통해 고객의 비즈니스를 돕고 있다. 역자 : 김은호 삼성전자 미디어 솔루션 센터에서 프로페셔널 커리어를 시작해 무선 사업부를 거치면서 계속해서 B2C 서비스의 개발 팀에서 경험을 쌓았다. 클라우드 컴퓨팅 기술을 적극적으로 활용해 지속적으로 변화하는 사용자들의 요구와 개발 팀이 구현해내는 아이디어를 안정적으로 빠르게 연결하는 목표를 달성하고자 일했다. 데브옵스(DevOps)와 SRE 등 여러 사례를 소속된 팀에 적용해 성과를 만들고자 노력했다. 이후 AWS의 솔루션즈 아키텍트로 자리를 옮겨 대규모 분산 시스템을 설계하고 운영했던 경험을 바탕으로 여러 도메인의 고객과 함께 주어진 비즈니스 문제 해결을 위해 일했고, 현재는 스타트업 회사인 인텔렉투스의 데이터플랫폼 솔루션 팀에서 다음 성과를 위한 도전을 이어나가고 있다.

1부. 웹 API 설계 소개 01장 API 설계 원칙 __웹 API 설계 요소 ____비즈니스 관점에서의 기능 ____프로덕트 중심 사고 ____개발자 경험 __API 설계는 커뮤니케이션 __소프트웨어 설계 원칙 다시 보기 ____모듈화 ____캡슐화 ____높은 응집도와 낮은 결합도 __리소스 기반 API 설계 ____리소스는 데이터 모델이 아니다 __리소스는 객체 또는 도메인 모델이 아니다 __리소스 기반 API 메시지 교환 __웹 API 설계 원칙 __요약 02장. API 설계 협업 __API 설계 프로세스를 사용하는 이유 __API 설계 프로세스 안티패턴 ____허술한 추상화 안티패턴 ____출시 버전마다 변경되는 설계 안티패턴 ____과잉 설계 안티패턴 ____미사용 API 안티패턴 __API 설계 우선 방법론 __API 설계 우선 방법론에서의 애자일 ____애자일 소프트웨어 개발 선언 ____API 설계 우선 방법론의 민첩성 __ADDR 프로세스 __API 설계에서 DDD의 역할 __모두가 참여하는 API 설계 __프로세스를 효과적으로 적용 __요약 2부. API 결과에 따른 조정 03장. 디지털 기능 식별 __이해관계자의 의견 수렴 __무엇이 디지털 기능인가? __수행해야 할 작업에 집중 __작업 스토리가 무엇인가? __작업 스토리의 구성 요소 __API에 대한 작업 스토리 작성 ____방법 1: 문제가 판명된 경우 ____방법 2: 원하는 결과를 알 수 있는 경우 ____방법 3: 디지털 기능이 식별된 경우 __작업 스토리의 어려움 극복 ____도전 1: 너무 상세한 작업 스토리 ____도전 2: 기능 중심의 작업 스토리 ____도전 3: 추가 사용자 콘텍스트가 필요한 작업 스토리 __작업 스토리 캡처 기술 __실제 API 설계 프로젝트 __작업 스토리 예제 __요약 04장. 액티비티와 단계 캡처 __작업 스토리를 액티비티 및 단계로 확장 ____각 작업 스토리를 위한 액티비티 식별 ____각 액티비티를 단계로 분해 ____요구 사항이 명확하지 않을 때 __공동 이해를 위한 EventStorming 사용 __EventStorming 동작 방식 ____단계 1. 비즈니스 도메인 이벤트 식별 ____단계 2. 이벤트 내러티브 만들기 ____단계 3. 내러티브 리뷰와 갭 식별 ____단계 4. 도메인 이해 확장 ____단계 5. 최종 내러티브 리뷰 __EventStorming의 장점 ____누가 참여해야 하는가? __EventStorming 세션 진행 ____준비: 필요한 물품 수집 ____공유: EventStorming 세션 전달 ____실행: EventStorming 세션 수행 ____정리: 액티비티와 액티비티 단계 캡처 ____후속 조치: 세션 후 권장 사항 ____프로세스의 개인화 __요약 3부. API 후보 정의 05장. API 경계 식별 __피해야 할 API 경계 구분의 안티패턴 ____여러 기능을 제공하게 거대해진 하나의 API 안티패턴 ____사용 목적이 과도하게 집약된 API 안티패턴 ____도우미 API 안티패턴 __제한된 콘텍스트와 하위 도메인 및 API __EventStorming을 이용한 API 경계 찾기 __액티비티를 통한 API 경계 찾기 __API 이름 지정과 범위 __요약 06장. API 모델링 __API 모델링 ____API 프로파일의 구조 __API 모델링 프로세스 ____단계 1: API 프로파일 요약 캡처 ____단계 2: 리소스 확인 ____단계 3: 리소스 분류 정의 ____단계 4: 작업 이벤트 추가 ____단계 5: 작업 세부 정보 확장 __시퀀스 다이어그램으로 API 모덜 검증 __API 중요도와 재사용 여부 평가 __요약 4부. API 설계 07장. REST API 설계 __REST API란? ____REST는 클라이언트와 서버다 ____REST는 리소스 중심이다 ____REST는 메시지 기반이다 ____REST는 계층 구조를 지원한다 ____REST는 코드온디멘드를 지원한다 ____하이퍼미디어 제어 ____언제 REST를 선택해야 하는가 __REST API 설계 프로세스 ____단계 1: 리소스 URL 경로 설계 ____단계 2: API 작업을 HTTP 메서드에 매핑 ____단계 3: 응답 코드 지정 ____단계 4: REST API 설계 문서화 ____단계 5: 공유하고 피드백 얻기 __리소스 표현 형식 선택 ____리소스 직렬화 ____하이퍼미디어 직렬화 ____하이퍼미디어 메시징 ____시맨틱 하이퍼미디어 메시징 __REST 설계 패턴 ____CRUD ____리소스 라이프사이클 확장 ____싱글톤 리소스 ____백그라운드(대기) 작업 ____REST에서 장기 실행 트랜잭션 처리 __요약 08장 RPC와 쿼리 기반 API 설계 __RPC 기반 API란? ____gRPC 프로토콜 ____RPC 고려 사항 __RPC API 설계 프로세스 ____단계 1: RPC 동작 식별 ____단계 2: RPC 동작 세부 내역 ____단계 3: API 설계 문서화 __쿼리 기반 API란? ____OData의 이해 ____GraphQL 알아보기 __쿼리 기반 API 설계 프로세스 ____단계 1: 리소스와 그래프 구조 설계 ____단계 2: 쿼리와 뮤테이션 동작 설계 ____단계 3: API 설계 문서화 __요약 09장. 이벤트와 스트리밍을 위한 비동기 API __API 폴링의 문제점 __비동기 API가 갖는 새로운 가능성 __메시징의 기초 다시 보기 ____메시지 스타일과 지역성 ____메시지의 구성 요소 ____메시지 브로커의 이해 ____P2P 메시지 배포(큐) ____팬아웃 메시지 배포(토픽) ____메시지 스트리밍의 기초 __비동기식 API ____웹훅을 이용한 서버 알림 ____SSE를 이용한 서버 푸시 ____웹소켓을 이용한 양방향 알림 ____gRPC 스트리밍 ____비동기 API 스타일 선택 __비동기 API 설계 ____명령 메시지 ____이벤트 알림 ____Event-Carried 상태 전달 이벤트 ____이벤트 일괄 처리 ____이벤트 순서 정렬 __비동기 API 문서 작성 __요약 5부. API 설계 개선 10장. API에서 마이크로서비스까지 __마이크로서비스란? __의견 조정 비용을 줄이는 마이크로서비스 __API와 마이크로서비스의 차이점 __마이크로서비스의 복잡성 평가 ____셀프 서비스 인프라 ____독립적인 배포 일정 ____단일 팀 관리 체계로 전환 ____조직의 구조 및 조직 문화의 변화 ____데이터 소유권의 이동 ____분산 데이터 관리 및 거버넌스 ____분산 시스템의 어려움 ____복원력, 장애 조치, 분산 트랜잭션 ____코드 리팩토링 코드 공유의 어려움 __동기식과 비동기식 마이크로서비스 __마이크로서비스 아키텍처 스타일 ____직접적인 서비스 통신 ____API 기반 오케스트레이션 ____셀 기반 아키텍처 __마이크로서비스의 크기 최적화 __API를 마이크로서비스로 분해 ____단계 1: 후보 마이크로서비스 식별 ____단계 2: API 다이어그램에 마이크로서비스 추가 ____단계 3: 마이크로서비스 설계 캔버스를 이용해 캡처 ____마이크로서비스 설계의 추가 고려 사항 __마이크로서비스 전환 시 고려 사항 __요약 11장. 개발자 경험 향상시키기 __모의 API 구현체 생성 ____정적 모의 API ____API 프로토타이핑 ____README 기반 모의 API __개발 라이브러리와 SDK 제공 ____개발 라이브러리 제공 방법 ____개발 라이브러리의 버전 관리 ____개발 라이브러리 문서와 테스트 __API를 위한 CLI 제공 __요약 12장. API 테스팅 전략 __인수 테스트 __자동화된 보안 테스트 __운영 모니터링 __API 계약 테스트 __효율적인 테스트를 위한 도구 선택 __API 테스트의 과제 __API 테스트는 선택이 아닌 필수 __요약 13장. API 설계 문서화 __API 문서화의 중요성 __API 설명 형식 ____OpenAPI 사양 ____API Blueprint ____RAML ____JSON 스키마 ____ALPS를 이용한 API 프로파일 ____APIs.json을 이용한 API 검색 개선 __코드 예제로 문서 확장 ____시작하기 코드 예제 먼저 작성 ____워크플로 예제로 문서 확장 ____에러 사례 및 운영 환경 준비가 된 예제 __참조 문서에서 개발자 포털로 ____개발자 포털을 통한 API 채택 증가 ____훌륭한 개발자 포털의 요소 __효과적인 API 문서화 ____질문1: API가 내 문제를 어떻게 해결하는가? ____질문2: 각 API 작업은 어떤 문제를 지원하는가? ____질문3: API 사용을 시작하려면 어떻게 해야 하는가? ____API 문서에서 테크니컬 라이터의 역할 __실행 가능한 최소 포털 ____단계 1: 실행 가능한 최소 포털 ____단계 2: 개선 ____단계 3: 성장에 집중 __개발자 포털을 위한 도구와 프레임워크 __요약 14장. 변화를 위한 설계 __기존 API 변경의 영향 ____API 설계 격차 분석 수행 ____API 소비자에게 가장 적합한 것이 무엇인지 결정 ____변경 전략 ____신뢰를 바탕으로 한 변경 관리 __API 버전 전략 ____일반적인 주요 변경 사항 ____호환되지 않는 변경 사항 ____API 버전과 개정판 ____API 버전 관리 방법 ____API 버전 관리의 비즈니스 고려 사항 __API 지원 중단 ____사용 중단 정책 수립 ____지원 중단 발표 ____API 안정성 계약 수립 __요약 15장. API 보안 __API 보안의 위험성 __API 보안의 필수 방법 __API 보안의 구성 요소 ____API 게이트웨이 ____API 관리 ____서비스 메시 ____웹 애플리케이션 방화벽(WAF) ____콘텐츠 전송 네트워크 ____지능형 API 보안 __API 게이트웨이 토폴로지 ____API 관리 호스팅 방법 ____API 네트워크 트래픽 고려 사항 ____토폴로지 1: API 게이트웨이를 API 서버로 직접 연결 ____토폴로지 2: 서비스에 대한 API 게이트웨이 라우팅 ____토폴로지 3: 여러 API 게이트웨이 인스턴스 __아이디 및 액세스 관리 ____암호와 API 키 ____API 토큰 ____참조를 전달하는 API 토큰과 값을 전달하는 API 토큰 ____OAuth 2.0과 OpenID Connect __API 게이트웨이를 직접 구축하기 전에 고려해야 할 사항 ____이유 1: API 보안은 움직이는 표적이다 ____이유 2: 예상보다 오래 걸린다 ____이유 3: 빠르게 작동하도록 만들기에는 많은 시간이 필요하다 ____개발 라이브러리에 대해 __요약 16장. API 설계 여정의 지속 __API 스타일 가이드 설정 ____스타일 가이드 준수를 장려하는 방법 ____스타일 가이드 어조 선택 ____API 스타일 가이드를 시작하기 위한 팁 ____여러 API 스타일 지원 __API 설계 검토 수행 ____문서 검토로 시작 ____표준 및 설계 일관성 확인 ____자동화된 테스트 범위 검토 ____미리 사용해보기 지원 추가 __재사용 문화 개발 __여정은 이제 막 시작됐다 부록 HTTP 입문서 __HTTP 개요 __URL __HTTP 요청 __HTTP 응답 __일반적인 HTTP 메서드 __HTTP 응답 코드 __콘텐츠 협상 __캐시 제어 __조건부 요청 __HTTP에서 동시성 제어 __요약

◈ 이 책에서 다루는 내용 ◈ ◆ 올바른 설계 프로세스를 통해 훌륭한 API 제공 ◆ 개발 팀, 고객, 기타 이해관계자로부터 구체적인 결과에 대한 합의 도출 ◆ 작업 스토리 작성, EventStorming 수행 및 기능 모델링 ◆ 올바른 API를 식별하고 일관된 API 프로파일로 작업을 구성 ◆ 각 프로젝트에 가장 적합한 스타일 선택: REST, gRPC, GraphQL 또는 이벤트 기반 비동기 API ◆ 문서 작성자, 테스터, 고객의 피드백을 바탕으로 디자인 개선 ◆ API를 마이크로서비스로 분리 ◆ 확장 가능한 설계 및 관리 프로세스를 구현해 API 프로그램 완성 ◈ 이 책의 대상 독자 ◈ 인간을 즐겁게 할 단일 API 또는 일련의 API를 설계하려는 모든 사람을 대상으로 한다. 제품 소유자와 제품 관리자는 팀이 API를 설계하는 데 필요한 요소를 더 깊이 이해할 수 있다. 소프트웨어 아키텍트와 개발자는 소프트웨어 아키텍처의 원리를 적용해 API를 설계하는 방법을 배우면 도움이 된다. 테크니컬 라이터는 API 문서의 명확성에 기여할 뿐만 아니라 API 설계 프로세스 전반에 걸쳐 가치를 추가할 수 있는 방법을 식별할 수 있다. 간단히 말해 『웹 API 설계 원칙』은 개발 또는 비개발 역할에 관계없이 API 설계에 관련된 모든 사람을 위한 것이다. ◈ 이 책의 구성 ◈ API 설계를 위한 일련의 원칙과 프로세스를 간략하게 설명하는 책이다. 이 책에서 다루는 ADDR 프로세스는 개인 및 여러 팀이 API 설계의 복잡성을 탐색하는 데 도움이 되도록 설계했다. 고객의 소리, 수행해야 할 작업, 프로세스 매핑과 같은 개념을 적용해 API 설계에 대한 객관적인 관점을 갖길 권장한다. 『웹 API 설계의 원칙』은 처음부터 새로운 예시를 통해 안내하지만 기존 API에도 사용될 수 있다. 이 책은 요구 사항 단계에서 고객에게 제공할 준비가 된 API 설계에 도달하는 것까지 API 설계의 모든 측면을 다룬다. 또한 개인, 팀 및 API 소비자 간의 좀 더 효과적인 의사소통을 위해 API 설계를 문서화하는 방법에 대한 지침도 포함돼 있다. 마지막으로 API 설계에 영향을 줄 수 있는 API 전달의 몇 가지 요소를 다룬다. 이 책은 5개의 부로 구성된다. ◆ 1부, ‘웹 API 설계 소개’에서는 API 설계가 중요한 이유에 대한 개요와 이 책에서 사용되는 API 설계 프로세스를 소개한다. ◆ 2부, ‘API 결과에 따른 조정’에서는 API를 설계하는 팀과 모든 고객 및 이해관계자 간의 조정을 보장한다. ◆ 3부, ‘API 후보 정의’에서는 API 프로파일에 원하는 결과를 제공하는 데 필요한 API 작업을 포함해 필요한 API를 식별한다. ◆ 4부, ‘API 설계’에서는 API 프로파일을 대상 개발자의 요구 사항을 충족하는 하나 이상의 API 스타일로 변환한다. 다루는 스타일에는 REST, gRPC, GraphQL, 이벤트 기반 비동기 API가 포함된다. ◆ 5부, ‘API 설계 개선’에서는 문서, 테스트 및 피드백에서 얻은 통찰력을 기반으로 API 설계를 개선한다. 또한 API를 마이크로서비스로 분해하는 장도 포함돼 있다. 마지막으로 이 책은 대규모 조직에서 설계 프로세스를 확장하는 방법에 대한 팁으로 마무리된다. 부록에서는 웹 기반 API에 사용되는 웹 언어인 HTTP에 대한 복습이 필요한 사람들을 위해 시작하는 데 도움이 되는 훌륭한 입문서를 제공한다. ◈ 옮긴이의 말 ◈ IT 업계에 적을 두고 있는 사람으로서 최근만큼 다채로운 주제가 다양한 방식으로 변화를 가져오는 경우가 이제껏 있었나 하는 생각이 든다. 모놀리식(Monolithic)에서 마이크로서비스 아키텍처(MicroService Architecture) 로의 전환은 업계 사람들 사이에서 가장 많이 논의되는 주제 중 하나다. 이미 소개된 많은 책이 이를 대변하고 있다. 바꿔 말하면 이미 많은 책과 글에서 마이크로서비스 아키텍처로 구성된 결과물을 두고 어떤 것이 마이크로서비스 아키텍처이고 왜 하는지를 설명하고 있다. 이 책은 마이크로서비스 아키텍처만을 소개하고자 작성된 책은 아니다. 오히려 설계 관점에서 비즈니스 문제를 어떻게 인식하고 어떠한 절차를 거쳐 API를 설계하는 것이 효과적이고 효율적인지 얘기한다. 그 과정에서 데이터 기반 설계(Data Driven Design) 패턴의 개념이 사용되기도 하고 API 설계의 한 결과로 마이크로서비스의 사례를 소개하기도 한다. AWS CEO였던 앤디 제시(Andy Jassy)는 언젠가 AWS의 공식 행사에서 연사로 나와 “경험을 압축하는 알고리듬은 없다.”고 말했다. 개인적으로 좋아하는 말이다. 누군가의 경험을 압축해서 내 것으로 만드는 방법은 없다. 하지만 누군가의 경험을 토대로 앞으로 나아갈 방향을 결정하는 데 참고하고 더 밀도 있는 자신만의 경험을 쌓을 수 있다. 현재 애플리케이션의 현대화를 고민 중이라면 이 책은 좋은 지침서가 될 것이다. -정영민 현대의 서비스에서 API가 얼마나 중요한지는 모두 알고 있다. 이 책은 API 설계를 위한 기술적 구현 방법보다는 프로덕트(비즈니스)에 집중하며 API라는 도구를 통해 어떻게 다양한 관계에 있는 이해관계자들과 목표를 일치시키고 커뮤니케이션할 수 있는지에 대해 초점을 맞추고 있다. 그리고 그 방법을 ADDR 프로세스를 통해 구체적으로 제안하고, 독자가 정확히 이해하고 도입할 수 있도록 자세히 설명하고 있다. 우리는 IT를 이용해 많은 일을 하고 있지만 여전히 사람과 함께 살고 있는 것처럼 이 책은 기술에만 초점을 맞춘 책과는 다른 인사이트를 제공한다. 꼭 개발자가 아니더라도 프로덕트 오너 그리고 기획/운영 팀 등 API를 통해 비즈니스를 하는 조직 내의 누구라도 읽어볼 수 있는 책으로, 조직의 API 설계 지침 기반을 만드는 작업에 유용한 도구가 될 것이다. -이혁 API는 비즈니스를 운영하는 조직에게 중요한 자산이다. 디지털 전환의 흐름 속에서 IT업계뿐 아니라 거의 모든 업계에서 API로 구현된 고유의 비즈니스 기능을 자산 관점에서 중요하게 여긴다. 잘 설계된 API는 직면한 비즈니스 문제를 효과적으로 해결하며, 지속적으로 변화하는 비즈니스 환경에서도 적시에 새로운 문제 해결을 위한 기반이 된다. 이 책은 이러한 실질적인 본질을 책 전반에 거쳐 현실적인 사례를 기반으로 전달하고 있다. 중요성을 잘 알면서도 어떻게 적용하는지 막막한 경우가 많다. 비즈니스 영역에 대한 이해와 기술적인 설계 및 고도화를 책 한 권으로 전부 습득할 수는 없을 것이다. 잘 정리된 이론과 저자의 경험, 실질적인 사례를 통해 이 문제 해결 방법을 체득한다면 이제 각자의 고유한 상황과 문제를 대입해서 새로운 성과를 만들 수 있을 것이다. -김은호