웹 API 디자인

아노드로렛

프랑스에서활동중인소프트웨어아키텍트로2002년부터금융업계에서웹서비스와API를활용한다중연결시스템을설계해왔다.로렛은API핸디맨이란블로그와API스타일북이라는웹사이트를운영중이며전세계에서열리는다양한API컨퍼런스에강연자로참여했다.인간중심의소프트웨어디자인을지향하며많은사람들에게최종사용자뿐만아니라운영팀과개발자까지모든이들이훌륭한경험을할수있는시스템을만들기를독려하고있다.

1부.API디자인기초

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

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

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

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

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

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

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

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

3부상황에맞는API디자인

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

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

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

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

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

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

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

1부.API디자인기초

API를디자인할때필요한기본개념과기술들을다룹니다.1장은API가무엇인지,디자인이왜중요한지API디자인을구성하는요소가무엇인지설명합니다.2장은API사용자의관점과API를사용하는소프트웨어의관점에초점을맞추어서API를노출시키지않는소프트웨어를만들고API의실제목표를결정하는방법을설명합니다.3장은HTTP프로토콜과RESTAPI,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검토를자세히살펴봅니다.