일상 속에서 찾는 웹 API의 디자인 원리

 

웹 API는 새로운 서비스나 앱을 만들 때 기존에 존재하던 서비스가 제공하는 기능을 활용할 수 있도록 해준다. 굳이 기존 서비스에 대한 자세한 소스 코드를 알지 않더라도 개발자가 만드는 프로젝트에 쉽게 맞아 들어가는 레고와 같은 존재라고 생각할 수 있다. 그렇다면 나의 서비스를 다른 개발자가, 다른 애플리케이션이 쉽게 사용할 수 있는 API는 어떻게 만들어야 할까?
10년이 넘는 경력 기간 동안 다양한 웹 API를 마주하고 디자인했던 아노드 로렛이 지금까지 웹 API 디자이너들의 머릿속에 감으로만 자리잡고 있던 노하우를 간단히 이해할 수 있는 개념으로 정리했다.
[일상 속 사물이 알려주는 웹 API 디자인]은 우리가 당연하게 여기고 깊이 탐구해보지는 않았던 일상 속 사물을 예로 들어 API의 디자인 방법을 소개한다. 버튼들이 뒤죽박죽으로 섞인 리모컨, 정해놓은 시간까지 초 단위로 카운트다운을 하는 알람시계같이 전혀 사용법을 알 수 없는 물건을 우리에게 익숙한 모습으로 되돌리는 과정을 보여주며 이를 웹 API 디자인 과정과 연결한다. API 디자인 자체에 대한 기초적인 이론과 실제로 사용하기 편한 웹 API를 디자인하는 방법, 실제로 웹 API를 운영하게 되었을 때 관리를 하는 방법까지 좋은 API를 제대로 디자인하는데 필요한 모든 개념을 담았다. 모던 웹 서비스를 만드는 이들이라면 반드시 알아야 할 지식을 손에 넣어보자.

 

이 책은 총 3부, 13장으로 구성되어 있습니다. 이 책은 모든 장을 처음부터 끝까지 순서대로 읽어야 합니다. 각각의 장은 이전 장에서 배운 내용을 확장해 나갑니다. 즉, 1, 2, 3장을 마쳐야 디자인에 관한 주제를 다루는 장으로 이동할 수 있습니다.

1부. API 디자인 기초

API를 디자인할 때 필요한 기본 개념과 기술들을 다룹니다. 1장은 API가 무엇인지, 디자인이 왜 중요한지 API 디자인을 구성하는 요소가 무엇인지 설명합니다. 2장은 API 사용자의 관점과 API를 사용하는 소프트웨어의 관점에 초점을 맞추어서 API를 노출시키지 않는 소프트웨어를 만들고 API의 실제 목표를 결정하는 방법을 설명합니다. 3장은 HTTP 프로토콜과 REST API, REST 아키텍처 스타일을 소개합니다. 4장은 OpenAPI 명세를 소개하며 목표를 기반으로 API 설명 형태로 API를 구조화하는 방법을 알려줍니다.

2부. 사용하기 좋은 API 디자인

이해하기 쉽고 사용하기 쉬운 API를 설계하는 방법에 중점을 둡니다. 5장은 사람들이 즉시 이해하고 쉽게 사용할 수 있도록 간단한 데이터 표현, 오류 및 성공 피드백, API 호출 흐름을 디자인하는 방법을 설명합니다. 6장은 컨슈머가 일관성 있고 적응 가능하며 검색 가능한 API를 만들어 작동 방식을 추측하기 쉬운 API 를 설계하는 방법을 설명합니다. 7장은 API의 모든 측면을 이해하고 사용하기 쉽게 구성하고 크기를 조정하는 방법을 보여줍니다.

3부. 상황에 맞는 API 디자인
API 디자이너가 API를 둘러싼 전체 컨텍스트와 API 디자인 프로세스 자체를 둘러싼 전체 컨텍스트를 고려 해야 하는 이유를 알려줍니다. 8장은 API 보안과 안전한 API를 디자인하는 법을 설명합니다. 9장은 사용자 들에게 영향을 끼치지 않고 API를 수정하는 법과 버저닝하는 방법을 알려줍니다. 업그레이드하기 좋은 API 를 만드는 방법도 소개합니다. 10장은 네트워크에 효율적인 웹 API를 디자인하는 방법을 분석합니다. 11장 은 API 설계자가 API를 설계할 때 고려해야 하는 전체 컨텍스트를 살펴봅니다. 여기에는 통신 메커니즘 조 정, 소비자 또는 공급자의 한계에 대한 평가 및 조정, 적절한 API 스타일 선택이 포함됩니다. 12장은 API 설계자가 OpenAPI 사양과 같은 API 설명 형식을 활용하여 다양한 유형의 API 문서를 작성하는 방법을 설명합니다. 13장은 전체 API 라이프 사이클을 살펴보고 API 디자이너가 여러 API에 참여해 다양한 API에 참여할 수 있는 방법을 소개합니다. 특히 API 설계 지침과 API 검토를 자세히 살펴봅니다.

1부. API 디자인 기초

1.\tAPI 디자인이란 무엇인가?
1.1\tAPI란 무엇인가?
1.1.1\t소프트웨어를 위한 웹 인터페이스
1.1.2\t소프트웨어를 레고처럼 바꾼다
1.2\tAPI 디자인이 중요한 이유
1.2.1\t퍼블릭, 프라이빗 API는 다른 개발자들도 사용한다
1.2.2\tAPI는 구현을 숨겨준다
1.2.3\tAPI를 어설프게 디자인하면 끔찍한 결과가 이어진다
1.3\tAPI 디자인에 필요한 요소
1.3.1\t프로그래밍 인터페이스 이상의 디자인 원리 이해
1.3.2\tAPI 디자인의 모든 측면

2.\t사용자를 위한 API 디자인하기
2.1\t일상 속 사용자 인터페이스를 디자인하는 올바른 관점
2.1.1\t작업 방식에 집중하면 인터페이스가 복잡해진다
2.1.2\t사용자가 할 수 있는 일에 집중하면 인터페이스는 단순해진다
2.2\t소프트웨어 인터페이스 디자인 방법
2.2.1\tAPI를 소프트웨어의 제어판처럼 바라보기
2.2.2\t컨슈머의 관점에 집중해 단순한 API를 만들기
2.3\tAPI의 목표 식별 과정
2.3.1\t무엇을 어떻게 하는가
2.3.2\t어떤 걸 입력하고 어떤 게 출력되는가
2.3.3\t누락된 목표가 있는가
2.3.4\t모든 사용자를 찾아냈는가
2.3.5\tAPI 목표 캔버스
2.4\tAPI 디자인에서 피해야 할 프로바이더 관점
2.4.1\t데이터가 미치는 영향
2.4.2\t코드와 비즈니스 로직이 주는 영향
2.4.3\t소프트웨어 아키텍처에서 받는 영향
2.4.4\t인적 조직으로 인한 영향
2.4.5\tAPI 목표 캔버스에서 프로바이더 관점 찾기

3.\t프로그래밍 인터페이스 디자인하기
3.1\tREST API 소개
3.1.1\tREST API 호출 분석
3.1.2\tHTTP의 기초사항
3.1.3\tREST API의 기초원리
3.2\tAPI 목표를 REST API로 변형하는 과정
3.2.1\tAPI 목표 캔버스로 리소스와 리소스 사이 관계 식별
3.2.2\tAPI 목표 캔버스를 이용해 액션과 액션의 파라미터 그리고 반환값 식별
3.2.3\t경로를 포함한 리소스 표현
3.2.4\tHTTP로 액션 표현
3.2.5\tREST API와 HTTP 치트시트
3.3\tAPI 데이터 디자인하기
3.3.1\t컨셉(Concept) 디자인
3.3.2\t컨셉에서 리스폰스 디자인
3.3.3\t컨셉과 리스폰스에서 파라미터 디자인
3.3.4\t데이터 소스에서 파라미터 확인
3.3.5\t그 외의 파라미터들 디자인
3.4\t디자인적 난관에 봉착했을 때 균형 유지하는 법
3.4.1\tREST 절충안 예시
3.4.2\t사용자 편의성과 규칙 준수 균형잡기
3.5\tAPI를 디자인할 때 REST가 중요한 이유
3.5.1\tREST 아키텍처 스타일 소개
3.5.2\tAPI 디자인에서의 REST 제약사항이 미치는 영향

4.\tAPI 명세 포맷을 이용한 API 디자인
4.1\tAPI 명세 포맷이란 무엇인가?
4.1.1\tOAS(OpenAPI Specification) 소개
4.1.2\t왜 API 명세 포맷을 사용해야 하는가?
4.1.3\tAPI 명세 포맷을 사용해야 할 때
4.2\tOAS를 통한 API 리소스와 액션 설명
4.2.1\tOAS 문서 생성
4.2.2\t리소스 설명
4.2.3\t리소스의 동작 설명
4.3\tOpenAPI와 JSON Schema로 API 데이터 표현하기
4.3.1\t쿼리 파라미터 묘사
4.3.2\tJSON Schema를 통한 데이터 묘사
4.3.3\t리스폰스 묘사
4.3.4\t바디 파라미터 묘사
4.4\tOAS에서 API를 효율적으로 묘사하기
4.4.1\t컴포넌트 재사용하기
4.4.2\t패스 파라미터(Path parameter) 묘사하기

2부 사용하기 좋은 API 디자인

5.\t직관적인 API 디자인하기
5.1\t직관적인 표현
5.1.1\t명확한 이름 정하기
5.1.2\t사용하기 쉬운 데이터 타입과 포맷 정하기
5.1.3\t바로 사용할 수 있는 데이터 선택하기
5.2\t직관적인 상호작용
5.2.1\t직관적인 입력 요청하기
5.2.2\t발생 가능한 모든 에러 피드백 식별하기
5.2.3\t유용한 에러 피드백 반환하기
5.2.4\t철저한 에러 피드백 반환하기
5.2.5\t유용한 성공 피드백 반환하기
5.3\t직관적인 흐름
5.3.1\t직관적인 목표 연쇄 만들기
5.3.2\t에러 방지
5.3.3\t목표 통합
5.3.4\t상태가 없는 흐름 디자인하기

6.\t예측 가능한 API 디자인하기
6.1\t일관성 유지하기
6.1.1\t일관된 데이터 디자인하기
6.1.2\t일관적인 목표 디자인하기
6.1.3\t일관성의 4단계
6.1.4\t타인을 따라하자: 일반적인 관행과 표준 준수하기
6.1.5\t유지하기 어렵고 현명하게 적용해야하는 일관성
6.2\t적응 가능하게 하기
6.2.1\t다른 포맷으로 제공하거나 응답하기
6.2.2\t국제화와 현지화
6.2.3\t필터, 페이지, 정렬 적용하기
6.3\t탐색 가능하게 하기
6.3.1\t메타데이터 제공하기
6.3.2\t하이퍼미디어 API 만들기
6.3.3\tHTTP 프로토콜의 장점 이용하기

7.\t간결하고 체계적인 API 디자인하기
7.1\tAPI 구조화
7.1.1\t데이터 구조화하기
7.1.2\t피드백 구조화하기
7.1.3\t목표 구조화하기
7.2\tAPI 사이징
7.2.1\t데이터 세분화 선택하기
7.2.2\t목표 세분화 선택하기
7.2.3\tAPI 세분화 선택하기

3부 상황에 맞는 API 디자인

8.\t안전한 API 디자인하기
8.1\tAPI 보안의 개요
8.1.1\t컨슈머 등록하기
8.1.2\tAPI 사용을 위해 자격증명 가져오기
8.1.3\tAPI 호출하기
8.1.4\t보안성 관점에서 API 구상하기
8.2\tAPI 분할을 통한 접근 제어 활성화
8.2.1\t유연하고 정제된 스코프 정의하기
8.2.2\t단순하지만 더 굵직한 스코프로 정의하기
8.2.3\t스코프 전략 선택하기
8.2.4\tAPI 명세 포맷으로 스코프 정의하기
8.3\t접근 제어를 고려한 설계
8.3.1\t접근 제어에 필요한 데이터 이해하기
8.3.2\t필요에 따른 디자인 조정
8.4\t민감 요소의 취급
8.4.1\t민감한 데이터 취급하기
8.4.2\t민감한 목표 취급하기
8.4.3\t안전한 에러 피드백 디자인하기
8.4.4\t아키텍처와 프로토콜 이슈 식별하기

9.\tAPI 디자인 발전시키기
9.1\tAPI 진화 디자인
9.1.1\t출력 데이터의 브레이킹 체인지 회피하기
9.1.2\t입력데이터와 파라미터에서 브레이킹 체인지 회피하기
9.1.3\t성공과 에러 피드백에서 브레이킹 체인지 회피하기
9.1.4\t목표와 흐름에서 브레이킹 체인지 회피하기
9.1.5\t브레이킹 체인지의 보안 취약점 발생 회피하기
9.1.6\t보이지 않는 인터페이스 컨트랙트에 주의하기
9.1.7\t브레이킹 체인지를 유발하는 것이 항상 문제는 아닙니다.
9.2\tAPI 버전 정하기
9.2.1\tAPI 버전 관리와 구현 버전 관리 비교
9.2.2\t컨슈머 관점에서 API 버전 표현 선택하기
9.2.3\tAPI 버저닝의 세분화 정하기
9.2.4\tAPI 버저닝이 디자인을 넘어 미치는 영향들
9.3\tAPI를 디자인할 때 확장성(Extensibility)을 명심하기
9.3.1\t확장 가능한 데이터 디자인하기
9.3.2\t확장가능한 상호작용 디자인하기
9.3.3\t확장 가능한 흐름 디자인하기
9.3.4\t확장가능한 API 디자인하기

10.\t네트워크 효율적인 API 디자인하기
10.1\t네트워크 커뮤니케이션의 고려사항의 개요
10.1.1\t장면 설정
10.1.2\t문제 분석하기
10.2\t프로토콜 레벨에서 네트워크 커뮤니케이션 효율성 보장하기
10.2.1\t압축(Compression)과 지속적인 연결(Persistent connections) 활성화하기
10.2.2\t캐싱(Caching)과 조건부 리퀘스트(Conditional request) 활성화 하기
10.2.3\t캐시 정책 선택하기
10.3\t디자인 레벨에서 네트워크 커뮤니케이션 효율성 확보하기
10.3.1\t필터링(Filtering) 활성화 하기
10.3.2\t목록 표현을 위한 연관된 데이터 선택하기
10.3.3\t데이터 집합체 만들기(Aggregating)
10.3.4\t다른 표현 제안하기
10.3.5\t확장 활성화하기
10.3.6\t쿼리 활성화하기
10.3.7\t보다 연관성 있는 데이터와 목표 제공하기
10.3.8\t다른 API 레이어 생성하기

11.\t컨텍스트에 맞는 API 디자인하기
11.1\t데이터와 목표와 성격에 맞는 커뮤니케이션 적용하기
11.1.1\t처리 시간이 오래 걸리는 작업 관리하기
11.1.2\t컨슈머에게 이벤트 알리기
11.1.3\t이벤트 흐름 스트리밍(Streaming)하기
11.1.4\t여러 요소(Element) 처리하기
11.2\t전체 컨텍스트 이해하기
11.2.1\t컨슈머의 기존 관행과 제약사항 숙지하기
11.2.2\t프로바이더의 한계를 신중하게 고려하기
11.3\t컨텍스트에 맞는 API 스타일 선택하기
11.3.1\t리소스, 데이터, 함수 기반 API 비교
11.3.2\t리퀘스트/리스폰스와 HTTP 기반의 API를 넘어서 생각하기

12.\tAPI 문서화 하기
12.1\t참조 문서 만들기
12.1.1\t데이터 모델 문서화
12.1.2\t목표 문서화하기
12.1.3\t보안 문서화하기
12.1.4\tAPI의 개요 제공하기
12.1.5\t세부구현에서 문서 추출하기: 장점과 단점
12.2\t사용자 안내서 작성하기
12.2.1\t유즈케이스 문서화하기
12.2.2\t보안 문서화하기
12.2.3\t일반적인 동작들과 원칙에 대한 개요 제공하기
12.2.4\t정적(Static) 문서화를 넘어서 생각하기
12.3\t구현 담당자에게 적절한 정보 제공하기
12.4\t문서의 개정과 폐기

13.\t성장하는 API
13.1\tAPI 생명주기(Lifecycle)
13.2\tAPI 디자인 지침 만들기
13.2.1\tAPI 디자인 지침에 포함되는 내용들
13.2.2\t지속적으로 지침 만들기
13.3\tAPI 리뷰하기
13.3.1\t요구사항에 도전하고 분석하기
13.3.2\t디자인 린트하기(Linting)
13.3.3\t프로바이더 관점에서 디자인 리뷰하기
13.3.4\t컨슈머 관점에서 디자인 리뷰하기
13.3.5\t구현 검증하기
13.4\t소통하고 공유하기