모던 API 아키텍처 설계 전략

0장 API 아키텍처 설계 여정을 시작하며
아키텍처 여정
API에 대한 간략한 소개
실전 예제: 컨퍼런스 시스템 사례 연구
__컨퍼런스 사례 연구의 API 종류
__컨퍼런스 시스템을 변경해야 하는 이유
__다계층 아키텍처에서 API 모델링으로의 전환
__사례 연구: 진화적 단계
__API 인프라스트럭처와 트래픽 패턴
__컨퍼런스 사례 연구의 로드맵
C4 다이어그램의 활용
__C4 컨텍스트 다이어그램
__C4 컨테이너 다이어그램
__C4 컴포넌트 다이어그램
ADR의 사용
__참석자 개선 ADR
__API 마스터하기: ADR 가이드라인
정리

[1부] API 설계부터 구현, 테스트까지

1장 API 설계, 구현, 명세
사례 연구: 참석자 API의 설계
REST에 대한 소개
__예시를 통한 REST와 HTTP 소개
__리처드슨 성숙도 모델
원격 프로시저 호출(RPC) API에 대한 소개
그래프QL에 대한 간단한 소개
REST API 표준과 구조
__컬렉션과 페이징
__컬렉션 필터링
__에러 처리
__ADR 가이드라인: API 표준의 선택
OpenAPI로 REST API 명세 작성하기
OpenAPI 명세의 실질적 활용
__코드 생성
__OpenAPI 검증
__예제와 모의 데이터
__변경의 탐지
API 버저닝
__시맨틱 버저닝
__OpenAPI 명세와 버저닝
gRPC로 RPC 구현하기
교환 방식과 API 형식의 선택
__트래픽이 높은 서비스
__대용량 데이터 페이로드
__HTTP/2의 성능 이점
__구형 형식들
가이드라인: 교환 데이터의 모델링
다중 명세
__월등한 명세는 존재하는가
__다중 명세를 제공할 때의 어려움
정리

2장 API 테스트
이번 장에서 다룰 컨퍼런스 시스템의 시나리오
테스트 전략
__테스트 사분면
__테스트 피라미드
__테스트 전략에 대한 ADR 가이드라인
계약 테스트
__계약 테스트를 더 선호하는 이유
__계약의 구현
__ADR 가이드라인: 계약 테스트
API 컴포넌트 테스트
__계약 테스트와 컴포넌트 테스트의 비교
__사례 연구: 컴포넌트 테스트로 동작 검증하기
API 통합 테스트
__스텁 서버를 사용해야 하는 이유와 방법
__ADR 가이드라인: 통합 테스트
__테스트 컴포넌트의 컨테이너화: Testcontainers
__사례 연구: Testcontainers를 이용한 통합 검증
종단 간 테스트
__종단 간 검증의 자동화
__종단 간 테스트의 종류
__ADR 가이드라인: 종단 간 테스트
정리

[2부] API 트래픽 관리

3장 API 게이트웨이: 인그레스 트래픽 관리
API 게이트웨이가 유일한 해결책일까?
가이드라인: 프록시, 로드밸런서 또는 API 게이트웨이의 선택
사례 연구: 참석자 서비스를 소비자에게 노출하기
API 게이트웨이의 정의
API 게이트웨이의 기능
API 게이트웨이의 배포 위치
API 게이트웨이와 다른 에지 기술의 통합
API 게이트웨이를 사용해야 하는 이유
__프론트엔드와 백엔드의 낮은 결합도: 어댑터/퍼사드 패턴의 활용
__사용법의 간소화: 백엔드 서비스의 종합과 해석
__남용 및 오용으로부터 API 보호: 위협 탐지와 완화
__API 활용 방식에 대한 이해: 관측용이성
__API를 제품으로 관리하기: API 수명주기 관리
__API의 수익화: 계정 관리, 비용 청구, 결제
모던 API 게이트웨이의 역사
__1990년대 이후: 하드웨어 로드밸런서
__2000년대 초반 이후: 소프트웨어 로드밸런서
__2000년대 중반: 애플리케이션 전달 컨트롤러(ADC)
__2010년대 초: 1세대 API 게이트웨이
__2015년 이후: 2세대 API 게이트웨이
현재의 API 게이트웨이 분류
__전통적인 엔터프라이즈 게이트웨이
__마이크로서비스/마이크로 게이트웨이
__서비스 메시 게이트웨이
__API 게이트웨이 유형 비교
사례 연구: API 게이트웨이를 이용한 컨퍼런스 시스템의 개선
__쿠버네티스에 엠버서더 에지 스택 설치하기
__URL 경로와 백엔드 서비스의 매핑 설정
__호스트 기반 라우팅을 이용한 매핑 설정
API 게이트웨이 배포: 장애에 대한 이해와 관리
__API 게이트웨이도 단일 실패 지점이다
__문제의 탐지와 해결
__장애와 문제의 해결
__위험의 완화
API 게이트웨이 구현의 보편적인 위험
__API 게이트웨이 루프백
__API 게이트웨이를 ESB처럼 활용
__모두가 거북이(API 게이트웨이)가 되는 현상
API 게이트웨이의 선택
__요구사항의 파악
__구현과 구입의 비교
__ADR 가이드라인: API 게이트웨이의 선택
정리

4장 서비스 메시: 서비스 간 트래픽 관리
서비스 메시가 유일한 해결책인가
가이드라인: 서비스 메시를 도입해야 할까
사례 연구: 세션 기능을 서비스로 분리하기
서비스 메시란
서비스 메시가 제공하는 기능들
서비스 메시를 배포하는 위치
서비스 메시는 다른 네트워크 토폴로지와 어떻게 통합될까
서비스 메시를 사용해야 하는 이유
__라우팅, 신뢰성, 트래픽 관리에 대한 세분화된 제어
__투명한 관측용이성의 제공
__보안의 적용: 전송 보안, 인증, 인가
__여러 언어의 교차 기능적 통신의 지원
__인그레스 트래픽과 서비스 간 트래픽 관리의 분리
서비스 메시의 진화
__초기의 역사와 그 동기
__구현 패턴
서비스 메시의 분류
사례 연구: 서비스 메시를 이용한 라우팅, 관측 가능성 그리고 보안
__이스티오를 이용한 라우팅
__링커드를 이용한 트래픽 관측
__콘설을 이용한 네트워크 분할
서비스 메시의 배포: 장애의 이해와 관리
__서비스 메시는 단일 실패 지점이다
서비스 메시 구현의 공통적인 어려움
__서비스 메시를 ESB로 사용하는 경우
__서비스 메시를 게이트웨이로 사용하는 경우
__네트워크 계층이 너무 많은 경우
서비스 메시의 선택
__요구사항 분석
__구현과 구입의 비교
__체크리스트: 서비스 메시의 선택
정리

[3부] API의 운영과 보안

5장 API의 배포와 릴리스
배포와 릴리스의 분리
__사례 연구: 기능 플래그
__트래픽 관리
사례 연구: 컨퍼런스 시스템의 릴리스 모델링
__API 수명주기
__수명주기에 릴리스 전략을 결합하기
__ADR 가이드라인: 트래픽 관리와 기능 플래그를 이용한 배포와 릴리스의 분리
릴리스 전략
__카나리 릴리스
__트래픽 미러링
__블루-그린
사례 연구: 아르고 롤아웃으로 롤아웃 수행하기
성공에 대한 모니터링과 장애의 인지
__관측용이성을 지탱하는 3가지 요소
__API에서 중요한 지표
__신호 읽어내기
효율적인 소프트웨어 릴리스를 위한 애플리케이션의 대응
__응답 캐싱
__애플리케이션 수준 헤더 전파
__디버깅을 돕기 위한 로깅
__규약형 플랫폼 고려하기
__ADR 가이드라인: 규약형 플랫폼
정리

6장 운영 보안: API의 위협 모델링
사례 연구: 참석자 API에 OWASP 적용하기
외부 API가 안전하지 않을 때의 위험
위협 모델링의 기초
공격자 입장에서 생각하기
위협 모델링 실습
__1단계: 목표를 정의한다
__2단계: 올바른 정보를 수집한다
__3단계: 시스템을 분할한다
__4단계: 위협을 정의한다(스트라이드의 활용)
__5단계: 위협의 위험도를 평가한다
__6단계: 검증한다
정리

7장 API의 인증과 인가
인증
__토큰을 이용한 최종 사용자 인증
__시스템 간 인증
__키와 사용자를 혼합하면 안 되는 이유
OAuth2
__API 사용 시 인가 서버의 역할
__JSON 웹 토큰(JWT)
__OAuth2 승인 관련 메커니즘과 용어
__ADR 가이드라인: OAuth2를 고려해야 할까
__인가 코드 승인
__리프레시 토큰
__클라이언트 자격증명 승인
__추가 OAuth2 승인
__ADR 가이드라인: 지원할 OAuth2 승인의 선택
__OAuth2 범위
__인가의 수행
OIDC 소개
SAML 2.0
정리

[4부] API의 진화적 아키텍처

8장 API 주도 아키텍처로의 재설계
시스템의 진화에 API가 필요한 이유
__유용한 추상화: 응집도의 향상
__도메인 경계의 정립: 낮은 결합도의 촉진
사례 연구: 참석자 도메인 경계의 확립
최종적인 아키텍처의 선택
__모놀리식
__서비스 지향 아키텍처
__마이크로서비스
__함수
진화적 절차의 관리
__목표의 결정
__적합성 함수의 활용
__시스템을 모듈로 나누기
__확장의 ‘이음새’가 될 API 구현하기
__시스템 내에서 변경 유발 지점 식별하기
__지속적 전달과 검증
API로 시스템을 진화시키기 위한 아키텍처적 패턴
__교살자 무화과나무
__퍼사드와 어댑터
__API 계층 케이크
어려운 부분과 기회를 식별하기
__업그레이드와 유지보수 이슈
__성능 이슈
__의존성의 제거: 결합도가 높은 API들
정리

9장 클라우드 플랫폼으로의 진화
사례 연구: 참석자 서비스를 클라우드로 이전하기
클라우드 마이그레이션 전략의 선택
__유지하거나 재검토
__호스트 교체
__플랫폼 교체
__재구매
__리팩토링/아키텍처 재설계
__퇴출
사례 연구: 참석자 서비스의 플랫폼을 클라우드로 교체하기
API 관리의 역할
수직 및 수평 트래픽: 트래픽 관리의 경계를 흐리게 하기
__에지부터 시작해 점차 내부로 마이그레이션을 수행하자
__경계 건너기: 네트워크 간 라우팅
구역화 아키텍처에서 제로 트러스트로의 이전
__구역으로의 진입
__아무도 믿지 말고 검증하자
__제로 트러스트 아키텍처에서 서비스 메시의 역할
정리

10장 지속적인 아키텍처 진화를 위해
사례 연구: 지금까지의 변화
API, 콘웨이의 법칙 그리고 여러분의 조직
의사결정 종류의 이해
미래를 위한 준비
__비동기 통신
__HTTP/3
__플랫폼 기반 메시
API 아키텍처를 계속 학습하기 위한 방법
__기반 기술을 계속해서 연마한다
__업계의 최신 정보를 얻는다
__레이더, 쿼드란트, 트렌드 리포트
__권장 기법과 사용 사례를 학습한다
__실전을 통해 학습한다
__가르치면서 학습한다

10여 년 전 「파이낸셜 타임스」에서 처음 API를 개발할 때만 해도 그렇게 많은 API를 개발하지는 않던 시기였다. 우리는 모놀리식 아키텍처를 채택했고 API는 서드파티가 우리 콘텐츠에 접근하게 하기 위한 용도로만 사용했었다.
하지만 지금은 어디에나 API가 존재하며 API야말로 성공적인 시스템 구현의 핵심이 되고 있다.
그 이유는 지난 10년간 몇 가지 요인으로 인해 우리가 소프트웨어를 개발하는 방식이 바뀌었기 때문이다.
첫 번째 요인은 우리가 사용할 수 있는 기술이 많이 달라졌다는 점이다. 클라우드 컴퓨팅의 등장으로 대고객용 서비스의 제작과 수요에 따른 프로비저닝이 가능해졌다. 자동화된 빌드와 배포 파이프라인 덕분에 지속적 통합과 배포가 가능해졌으며, 컨테이너 및 오케스트레이션 같은 관련 기술로 인해 작고 독립적인 서비스로 하나의 분산 서비스를 구성할 수 있게 됐다.
그렇게 하는 이유는 뭘까? 바로 두 번째 요인 때문이다. 연구 결과에 따르면 소프트웨어를 성공적으로 개발하는 조직은 느슨하게 결합된 아키텍처를 채택하고 있으며 팀에 자율성과 권한을 부여한다. 여기서 성공적이라는 단어는 비즈니스에 긍정적인 영향, 즉 시장 점유율, 생산성, 수익성의 증가 등을 의미한다.
요즘 채택하는 아키텍처는 결합이 느슨하며 분산 환경에서 API를 활용해 구현하는 경향이 있다. 따라서 발견 가능하고 일관적이며, 설령 예상치 못하게 변경되거나 사라져도 고객에게 문제를 유발할 가능성이 낮은 API를 구현하고 싶을 것이다. 이 외의 방법들은 서로 결합되어 동작하며 팀의 속도를 저하시킨다.
이 책의 저자인 제임스, 대니얼, 매튜는 효과적인 API 아키텍처를 구현하기 위한 포괄적이면서도 실용적인 가이드를 제공한다. 개별 API를 개발하고 테스트하는 기본적인 것부터 그 API를 배포할 생태계, 이를 효과적으로 릴리스하고 운영하는 방법 그리고 더 중요한 주제, 즉 API를 이용해 아키텍처의 진화를 이끌어내는 방법에 이르기까지 수많은 주제를 다룬다. 내가 처음 「파이낸셜 타임스」에서 개발했던 API는 이제 더 이상 존재하지 않으며, 해당 시스템을 처음부터 다시 개발했다. 그 과정에는 비용이 따른다. 제임스, 대니얼, 매튜는 API를 핵심 도구로 사용해 불가피한 변화를 다루고 시스템을 진화시키는 방법에 대한 템플릿을 제공한다.
소프트웨어 아키텍처는 중요하기도 하지만 바꾸기 어려운 결정에 의해 정의되어 왔다. 이런 결정은 프로젝트의 성패 여부를 결정한다.
저자들은 추상적인 아키텍처가 아니라 여러분의 조직에 아키텍처를 적용하는 방법에 집중한다. API 게이트웨이 또는 서비스 메시를 도입하고 또 그중 어떤 것을 도입할 것인지를 결정하는 것이 바로 되돌리기 어려운 결정이므로 주의를 기울여 조심히 평가해야 할 결정이다. 제임스, 대니얼, 매튜는 적절한 경우에는 규약이 명확한 가이드를 제시하며, 옵션이 명확하지 않을 때는 여러분의 상황에 맞는 최선의 선택을 내릴 수 있는 프레임워크를 제공한다.
저자들은 실용적이면서도 실질적인 사례 연구를 통해 개념을 소개하고 실제로 동작하게 만드는 방법을 보여준다. 이 책에서 소개하는 사례 연구는 마치 실제 시스템처럼 책을 읽어가는 동안 계속해서 개선된다. 저자들은 모든 것을 미리 할 필요는 없다는 점을 보여준다. 여러분은 필요에 따라 아키텍처를 조금씩 개선하고 서비스를 추출하며 API 게이트웨이와 서비스 메시 같은 도구를 추가해 가면 된다.
나는 첫 API를 개발하면서 무수히 많은 실수를 저질렀다. 그때 이 책이 있었더라면 방향을 이해하고 더 유용한 결정을 내리는 데 큰 도움이 되었을 것이다.
API를 중점적으로 활용하는 시스템을 다루는 사람이라면 누구나 이 책을 읽어볼 것을 강력히 권한다. 이 책을 통해 조직 내에서 API를 구현하는 모든 팀을 지원하기 위한 도구와 표준을 구현해낼 수 있을 것이다.
- 사라 웰스(Sarah Wells) / QCon 런던 컨퍼런스의 공동 운영자, 독립 컨설턴트이자 전 「파이낸셜 타임스」의 기술 디렉터