| 이 책에서 다루는 내용 |
이 책은 API를 기술하고(describe) 설계하는(design) 방법을 다룬다. OpenAPI 세상으로 인도하는 입문서로서, 설계 우선 원칙을 실천하는 API 개발자가 사용하는 도구와 사례를 들여다본다.
OpenAPI 정의서를 읽고 쓰는 기초부터 시작해서 도메인 설계, 워크플로 변경, API 디자인 패턴으로 나아간다. OpenAPI와 API 설계에 초점을 맞추지만 API 라이프사이클 전반에 걸친 주제를 모두 다루려고 노력했으며 기술 관점과 프로젝트 관리 관점을 두루 살펴볼 수 있다.
OpenAPI가 어떤 문제를 해결해 주는지, 왜 존재하는지, 어떻게 사용하는지 이해하고 자신감을 갖는 데 이 책이 도움이 되었으면 한다.

- OpenAPI 형식으로 기존 제품의 API를 기술해 본다
- OpenAPI와 스웨거를 활용해 API 설계 우선 방식(design first approach)을 적용해 본다
- 제품 출시 이후 API 확장과 진화 방법을 알아본다
- OpenAPI 구문과 구조를 학습한다
- 스웨거를 사용해 OpenAPI 정의서를 생성한다
- 프로세스를 자동화하고 코드를 자동 생성해 본다
- 기능 조직 간 협업 방식을 배운다

| 이 책의 대상 독자 |
API에 흥미를 갖고 설계 우선 방식으로 API를 활용해 보려는 소프트웨어 개발자가 읽어야 하는 책이다. 프론트엔드 또는 백엔드 개발자, 제품 관리자, QA 테스터, 심지어 CEO까지 API 관련 의사결정을 내려야 하는 모두가 읽어야 한다.
특정 주제를 심도 깊이 이해하고 있지 않더라도 책을 읽을 수 있도록 주의를 기울였으며, JSON이나 HTTP 같은 개념에 익숙하다면 책을 읽는 데 아무런 문제가 없을 것이다. 또한 간단한 복습과 외부 자료에 대한 링크도 많이 담았다.

| 이 책의 구성 |
[1부] OpenAPI 형식으로 기존 제품의 API를 기술해 보기
● 1장: API를 기술하는 의의와 방법
● 2장: API를 탐험하는 데 사용하는 도구인 포스트맨(Postman) 설명
● 3장: 이미 만들어져 있는 직판장(Farmstall) API를 기술하는 방법
● 4장: 스웨거 에디터 사용 방법
● 5장: 기본적인 API 요청과 응답 기술해 보기
● 6장: 요청 본문과 응답 본문 다뤄 보기
● 7장: 인증과 인가 알아보기
● 8장: 스웨거 UI를 사용해 API 문서를 제공하는 웹사이트를 호스팅하는 방법

[2부] 백지 상태에서 OpenAPI와 스웨거를 활용해 API를 설계해 보기
● 9장: 2부 전반에 걸쳐 다루게 될 펫시터(PetSitter) 프로젝트 소개
● 10장: API를 설계하고 OpenAPI를 사용해 API를 기술하는 과정
● 11장: API 설계 변경을 처리할 수 있는 깃(Git) 기반의 워크플로 소개
● 12장: API 사용자 입장에서 API에 대한 목(mock)을 활용하고 변경에 대응하는 방법
● 13장: 스웨거 코드젠을 사용해 API를 구현하는 방법
● 14장: API를 사용할 수 있도록 준비를 마치고 프론트엔드와 백엔드를 통합하는 과정

[3부] 2부에서 작성한 API 설계를 확장하고 진화시켜 보기
● 15장: 다음 단계의 API 반복(iteration)에 대한 계획 세우기
● 16장: JSON 스키마 합성(composition)을 사용한 도메인 모델 확장
● 17장: API에 필터링, 페이징, 정렬 기능 추가
● 18장: problem+json 응답 형식을 알아보고 API에 에러 처리 적용하기
● 19장: JSON 스키마를 확장하고 입력값 유효성 검증 적용하기
● 20장: API 버전 관리와 중대 변경(breaking change)을 처리하는 방법
● 21장: API 최종 출시 전 체크리스트

[부록] 스웨거 2.0, OpenAPI 3.0, OpenAPI 3.1의 차이점
[한국어판 특별부록] 스프링 부트 웹서비스에 스웨거를 입혀 활용하는 방법

[옮긴이의 말]
인터넷이 세상에 나온 지 그리 오래되지 않았을 때, 집 밖에 나가지 않고 인터넷만으로 얼마나 잘 지낼 수 있는지를 실험해보는 체험 예능 컨텐츠가 있었던 걸로 기억합니다. 하지만 이제 그런 예능은 아무도 보지 않을 것 같습니다. 스마트폰을 사용할 수 있다면 누구든 인터넷만으로 불편 없는 삶을 영위할 수 있다는 사실을 누구나 알고 있으니까요.
이처럼 손 안에서 몇 번의 스와이프와 클릭만으로 물건을 받아 사용할 수 있고 음식을 배달받아 먹으며, SNS를 통해 이 모든 것을 자랑까지 할 수 있게 된 편리한 세상을 돋보기로 계속 확대하면서 들여다보면 그 마디마디에 API가 숨어 있음을 확인할 수 있을 것입니다. API는 다양한 소프트웨어의 연결점 역할을 하면서 이 세상을 든든하게 떠받치고 있습니다.
소프트웨어의 연결점 역할을 하는 API는 소프트웨어 개발자들에게는 의사소통 수단으로 사용됩니다. 원활한 의사소통을 위해서는 주고받는 데이터 형식과 호출 방식을 정의하는 규격과 그에 대한 친절한 설명을 작성해야 합니다. 즉 API를 기술해야(describe) 합니다. OpenAPI는 HTTP 프로토콜 기반의 HTTP API를 기술하는 표준 명세이며, 표준이 있으면 자동화가 가능해지므로 OpenAPI를 통해 많은 작업을 자동화할 수 있습니다.
이 책은 OpenAPI를 사용해서 API 정의서를 기술하는 방법을 설명합니다. 그걸로 그쳤다면 그다지 재미없는 책이 될 수도 있었을 텐데, 작은 웹 서비스의 요구 사항을 정리하고, 사용자 스토리를 작성하고, 이를 바탕으로 비즈니스 도메인 모델을 설계하고, 이를 반영한 API를 설계하고, OpenAPI를 사용해서 API 정의서를 작성하고, 정의서를 바탕으로 자동화를 이용해 개발 생산성을 높이고, 시간이 지남에 따라 API를 매끄럽게 진화시켜 확장하는 방법까지 그야말로 모든 것을 다루고 있습니다.
API를 설계하고는 있지만 어쩌면 별다른 학습이나 기준 없이 편의성만을 생각하며 설계하고 구현하다가 나중에 확장하기 어렵게 되는 안타까운 일이 실무적으로 많이 발생하는데, 이 책에 나오는 모범 사례를 읽다 보면 자연스럽게 확장성 있는 API를 설계하는 데 필요한 지식을 얻을 수 있습니다.
이런 내용만으로도 유익할 텐데, 이 모든 과정을 지루하고 딱딱한 설명이 아니라 실제로 작은 프로젝트 팀이 구성되고 각자의 역할을 수행하며 난관에 부딪치고 해결하는 모습을 묘사하는 형식으로 전개하고 있어 흥미진진하고 재미있기까지 합니다. 게다가 예제를 위해 간혹 특정 기술을 사용하고 있기는 하지만 본질적으로 특정 도구에 종속되는 내용이 아니라서, 한마디로 API를 만들고 활용하는 개발자 모두에게 재미있고 유익한 책입니다.
이 책의 내용이 전반적으로 OpenAPI를 사용해 새로운 시스템을 설계하고 만들어 가는 과정을 보여주고 있어서 이미 만들어진 시스템에는 적용할 수 없는 건가라는 의문이 들 수도 있는데, 다행스럽게도 기존 시스템에도 적용할 방법이 있습니다. 국내에서 API 서버 개발에 가장 널리 사용되는 스프링 부트 기반의 API 서버라면 아주 간단한 설정과 애너테이션만으로도 스웨거 UI 사이트를 자동으로 만들 수 있습니다. 단순한 예제지만 실무적으로 꽤 큰 도움이 될 것이라 생각해서 한국어판 특별부록으로 추가했습니다.
코딩도 그렇지만 번역도 늘 볼 때마다 개선점이 눈에 보입니다. 아마 원서를 작성한 저자들도 마찬가지일 겁니다. 번역자는 일차적으로는 원서를 우리글로 옮기는 일을 하는 사람이지만, 훌륭한 번역자는 먼저 독자의 입장에서 원서를 읽고 불편했던 점을 찾아 개선하고 최종 독자에게는 더 나은 결과물을 보여주는 사람이라고 생각합니다. 이번에도 모자람이 있겠지만 훌륭한 번역자 흉내라도 내보고 싶어서 원서보다 나은 역서를 목표로 번역 작업을 했습니다. 모쪼록 독자분들이 읽어나가시면서 마치 애초부터 한글로 쓰여진 책인 것처럼 술술 읽으실 수 있기를 욕심내어 바라봅니다.