[독후감] 실전 API설계
API 소비자(?) 입장에서도 유익한 책
2011년부터 안드로이드 앱 개발을 해 왔으니 앱 개발도 벌써 13년이 되어간다. 앱 개발자 입장에서 업무에 가장 큰 도움을 준 혁신적인 도구론 디자인 도구인 figma와 API 문서 도구인 swagger를 꼽을 수 있겠다. 디자이너와의 협업의 경우, 옛날 옛적에 거대한 png에 디자이너분들이 한 땀 한 땀 가이드를 넣었던 시절에서 zeplin을 지나 이젠 완전히 figma 세상이 되었다. 이 도구 없이 어떻게 살았나 싶을 정도로 figma는 디자이너-개발자 협업 환경을 바꾸어놓았다. 앱 개발자의 또 다른 협업의 한 축인 백엔드 개발자와의 소통은 swagger 문서로 한다. 그나마 figma의 경우 옛날의 대왕 png 가이드 이미지 시절이 기억나는데, swagger의 경우 이 전에 대체 어떻게 소통을 했었는지 아예 기억이 안 난다. ms word로 했나? wiki? MSN 메시지? 아예 기억이 안 나네.
여하튼 백엔드 개발자분들이 만든 swagger 문서의 소비자로 살아온 지도 꽤 되었다. 나도 예전엔 백엔드 개발자이긴 했지만, 이 swagger를 어떻게 만드는지 별로 궁금해하진 않았다. 그래도 이 책 덕분에 오, 이런 과정을 거쳐 내가 보는 swagger 페이지가 만들어지는구나 알게 되어 재밌었다.
OpenAPI 스펙이라는 게 앱 개발자로 있는 동안은 절대 쓸 일 없는 그런 것인가? 싶었는데 의외의 필요처를 발견했다. 요즘 핫한 ChatGPT의 GPT action를 만들 때 OpenAPI로 명세를 작성해야 한다. 아마 선구적인 ChatGPT에서 이런 방식을 썼으니, 앞으로 다른 LLM 서비스의 플러그인을 만들기 위해서라도 OpenAPI 명세에 대해서 대략적으론 알고 있어야 할 듯하다. 당장 필요하진 않지만 그런 날이 올 때 이 책을 다시 한번 펼쳐볼 듯하다.
책 제목이 실전 API 설계이듯, swagger를 활용한 API 문서화뿐 아니라 git/github을 이용한 API 설계 워크플로우를 설명하는 부분도 흥미로웠다. 회사에서 일을 할 때는 보통 다음과 같은 흐름으로 일했다.
1. 클라이언트 개발자와 백엔드 개발자끼리 회의한다.
2. 백엔드 개발자가 API를 만들어 줄 때까지 놀거나(...) 화면을 만든다.
3. 백엔드 개발자가 API를 공유해 주면 내용에 대해 핑퐁을 한다. 그런데 이 시점엔 이미 백엔드 개발자가 상당 부분 개발 혹은 설계를 진행한 상태이기 때문에 많이 흔들기가 조금 미안하다. (하지만 할 말은 다 하지만)
반면 이 책에선 아예 API의 소비자가 API 스펙을 만드는 플로우를 소개한다. 역시 목마른 놈이 우물을 파는 법이지! 책의 소비자는 웹 프런트엔드라서 나랑은 좀 다르긴 하지만. 재밌는 시각이긴 한데, 사내 서비스의 API 들은 백엔드의 내부 데이터구조(RBD가 되었건 NoSQL이 되었건)를 상당 부분 반영해서 만드는 편이 백엔드 입장에서 효율적이라서 실전에 써먹긴 어렵지 않을까 싶긴 하다. 당장 나보고 API 만들라고 시키면 내 일이 더 늘어나기도 하고. 또 기껏 만들어봤자 백엔드 쪽에서 내부 자료구조와 맞지 않거나, 서버의 설계 의도와 맞지 않아 바꿔달라고 하는 일도 많지 않으려나? 결국 이렇게 핑퐁 하면 서버가 주도적으로 만들어서 클라이언트와 핑퐁 하는 것과 결과적으론 크게 다르지 않을까 싶기도 하다. 이것저것 다 고려하면 여전히 API 설계는 백엔드가 주도하는 게 맞지 않나 싶다. 종종 클라이언트에서 너무 쓰기 힘들게 만들어주는 경우도 있긴 한데, 이런 경우는 전체 비율에서 크진 않으니. (내가 일 더 하기 싫어서 그러는 게 맞다...)
여러 이해당사자의 합의하에 API를 변경하고, 이 과정에서 개별 이해당사자들이 변경된 API를 어디까지 이해하고 반영했는지 관리하는 API 설계 워크 플로우는 매우 신선했다. 우선 API 스펙 변경 부분에서 변경하고자 하는 API를 반영하여 수정한 OpenAPI 스키마를 main 브랜치에 반영하기 위한 PR을 만들고, 리뷰어로 다른 이해당사자들을 지정해서, 이해당사자들의 리뷰와 동의 (PR 승인)를 거치는 과정은 얼추 상상이 가는 부분이다. 재밌는 건 각 이해당사자들이 자신들의 branch를 가지고 있고, 이 branch는 각자가 이해한 main의 커밋을 가리키기 때문에 main과 diff를 하면 바로 현재 내가 이해한 부분과 main의 차이 (내가 앞으로 반영해야 할 API들로 해석할 수도 있겠다)를 바로 알 수 있는 점이다. 근데 문제가 나의 작업이 꼭 main 브랜치의 커밋 순서와 동일할 수가 없기 때문에 이게 잘 될까? 싶기는 하다. 현업에서 쓸 수 있을까? 난 안 쓸듯... 그래도 이런 아이디어는 다른 곳에도 활용할 수 있겠다.
앱 클라이언트 개발자가 꼭 읽어야 할 책인가? 클라이언트 개발자가 API의 생산자가 될 경우는 거의 없기 때문에 꼭 읽어야 할 책은 아니라고 본다. 클라이언트 개발자라면 SDK 배포를 할 순 있지만, SDK는 javadoc 등으로 API를 문서화하기 때문에, OpenAPI 를 이용할 일은 없다. 하지만 굉장히 자주 들여다볼 스웨거 페이지가 어떤 식으로 만들어지는지, 그리고 언젠가 써먹을 날이 올지도 모를 OpenAPI라는 게 뭔지 이해하는 데에는 좋은 길잡이가 되는 책이라고 생각한다.
