◈ 이 책에서 다루는 내용 ◈

◆ 올바른 설계 프로세스를 통해 훌륭한 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에 대한 복습이 필요한 사람들을 위해 시작하는 데 도움이 되는 훌륭한 입문서를 제공한다.

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에서 동시성 제어
__요약