Tech

단 하나의 API 사이트를 위한 여정 - Part 1

API 사이트를 위한 첫걸음 🚶‍♂️

2022-05-20

안녕하세요. 페이히어 CTO 안성현입니다.

페이히어는 모놀리틱 서버를 가지고 있습니다. 하지만 조직 구조를 스쿼드로 변경하고 그에 따른 기능적 배포 독립화 그리고 더 유연한 비지니스 대응을 위해서, 2021 하반기부터 본격적이고 점진적인 MSA로의 여정을 시작했습니다.

페이히어에서는 2021년부터 API 문서화를 본격적으로 swagger를 이용해서 하고 있습니다. 그러나 2021년 3분기부터 서비스가 늘어나면서 여러 서비스의 swagger를 어떻게 관리하고 보여줄지에 대한 고민이 생겼습니다. 그 당시 했던 고민은 아래와 같습니다.

서비스별 API가 swagger로 있는데 이것을 어떻게 하나의 API 사이트에서 보여줄 수 있을까?
여러 개의 swagger를 어떻게 관리 할 것인가?
하나의 API 사이트를 어떻게 하면 내부 구성원만 접속하게 할 수 있을까?

배경

view의 파편화

서비스가 다양해지면서 API 문서화를 한 곳에서 보고자 하는 니즈가 생겼습니다. 클라이언트 개발자는 외부로 노출되는 하나의 API를 주로 참고 하지만 서버 개발자는 여러 서버의 여러 API를 보고 구현해야 하는 경우가 있는데, 이런 경우 여러 개의 다른 도메인의 사이트를 접속해야 하는 번거로운 문제가 있었습니다. 😨

작성의 파편화

모놀리틱 서버는 Django DRF로 구현이 되어 있어서 drf-yasg를 사용하고 있습니다. 그러나 서버가 늘어나면서 golang, kotlin/spring, fastapi 등으로 구현된 API들이 생기게 되었고 그로 인해서 swagger를 만들어 내는 방식도 모두 달랐습니다. 서버와 함께 별도의 /doc 경로에 뜨는 경우가 있고, 로컬 파일로 swagger가 생성되는 경우도 있었습니다.

✨ Source of Truth

swagger는 어디에 있어야 할까?

보여주는 API 사이트를 단일화하는 것에 앞서 작성 및 관리하는 방식을 통일해야 한다는 생각을 하게 되었습니다. 그 이유는 개발의 효율화 때문이었습니다. 개발자가 다른 서비스의 GitHub Repository에 가서 API 문서화를 찾거나 혹은 수정 시 문서화에 대한 반영을 어떻게 해야 할지 각각 다르다면, 이전 작업자 혹은 CODEOWNER에게 계속 물어봐야 하기 때문에 커뮤니케이션 비용이 증가한다고 생각했습니다. 때문에 아래와 같은 규칙을 정했습니다.

각 GitHub Repository 최상단 /docs 디렉토리 하위에 swagger 파일을 위치시킨다.
해당 파일은 현재 main branch의 작업내용이 최신으로 반영이 되어야 한다.

무조건 docs 하위의 디렉토리에 swagger 파일을 위치시키도록 했습니다. 그래서 개발자가 다른 repository를 보더라도 swagger가 어디에 있는지 찾거나 묻지 않도록 했습니다. 또한 하나의 swagger repository가 아닌 개별 서버 repository에 swagger 파일을 위치시킨 것은, 해당 서비스를 관리하는 개발자가 문서화까지 모두 담당하게 하기 위함이었습니다. 개발자라면 본인이 만든 서비스에 대한 API 문서화도 책임을 져야 한다고 생각했고, 그에 대한 관리 위치도 해당 서버의 소스 코드와 같은 repository에 위치시켰습니다.

단 하나의 API 사이트

작성을 통일한 이후에는 단 하나의 API 사이트를 만들어야겠다는 생각을 하게 되었습니다. 기존의 모놀리틱 서버에 대한 API 문서화 사이트가 있었지만, 다른 API들이 생겨나면서 여러 개의 주소로 사이트를 열어서 봐야 하는 문제가 있었습니다. 또한 점점 서비스가 많아질수록 문서화 사이트를 찾기가 더 어려웠습니다.

때문에 페이히어 개발자들이 모두 다 같이 볼 수 있고, 단 하나의 주소로 접속할 수 있는 API 문서화 사이트가 필요하다고 생각했습니다. 그래서 클라이언트 개발자가 해당 사이트를 통해서 API 문서를 확인하고, 그 링크를 통해서 협업하는 서버 개발자는 개발계에 배포된 API를 JSON payload가 아닌 API 문서화 사이트의 특정 링크를 슬랙으로 전달하는 그림을 상상했습니다. 😚

보안 그리고 보안.

단 하나의 사이트를 만든다고 했을 때 가장 큰 고민은 보안에 대한 고민이었습니다. 페이히어의 개발자만 볼 수 있어야 한다고 생각했습니다. 외부 API나 오픈 API가 아닌 결제와 관련된 부분이기 때문에, 내부 구성원만 접근할 수 있게 만들고 싶었습니다. 어떻게 하면 이것이 가능하게 할 수 있을까요? 자체적인 접근 제어 시스템을 만들어야 할지, 혹은 큰 규모의 스타트업에서 많이 사용하는 SSO나 OKTA를 이용해야 할까를 고민을 하게 되었습니다.

✨ 오픈소스로 해결하기

큰 리소스를 들이지 않고 해결하고 싶었습니다. 스타트업에서 제일 중요한 것은 고객과 제품 그리고 성장이기 때문에, 성장과 직접적인 관련이 없는 부분에 많은 리소스를 할애하는 것은 현실적으로 어렵다고 생각했습니다.
그래서 API 문서화 사이트를 자체적으로 구축하는 방향은 지양하고 오픈소스를 사용해서 해결하고자 했습니다. 🤟

multiple swagger 를 한 곳에서 보여주기

어떻게 하면 multiple swagger를 한 사이트에서 볼 수 있을까를 검색하다 volbrene/redoc을 알게 되었습니다. 기존에 모놀리틱에서 사용하던 redoc 스타일의 사이트로 보여주면서, 첫 화면에서 여러 API를 선택할 수 있는 dropdown 형태의 UI 그리고 각 API 상세 사이트 우측 상단에 다른 API 문서화 사이트로 이동할 수 있는 수단을 제공했습니다. docker의 형태로 되어 있어서 바로 사용할 수 있었고 docker volume으로 연결하려는 swagger 파일을 넣을 수 있었습니다.

어떻게 repository의 swagger file을 가져올 것인가?

해당 오픈소스를 사용하기로 한 이후 추가적으로 해야하는 작업이 있었습니다. 각 repository/docs/ 하위의 최신의 swagger 파일을 어떻게 가져올까에 대한 기술적 고민이 있었습니다.
이에 대한 구현 방법으로 cron을 통해서 github repo의 특정 url의 swagger 파일을 가져오도록 했습니다. 그리고 특정 경로를 docker volume을 이용해서 연결하는 작업을 진행했습니다. 지금 생각하면 PR Merge 같은 GitHub Actions 이용해서 처리 할 수도 있을 것 같은데, 구현 당시에는 단순하게 최신의 swagger를 유지하기 위해서 cron으로 주기적으로 대상 repository의 파일을 가져오는 식으로 구현했습니다.

보안 적용하기

OKTA나 SSO를 적용하는 건 닭 잡는데 소 잡는 칼을 사용하는 것 같았습니다. 한마디로 오버엔지니어링이 아닌가 하는 생각이 들었고, 관련해서 찾아보니 oauth proxy를 통해서 @payhere.in google workspace 계정을 가진 사람만 로그인을 통해서 체크할 수 있다는 것을 알게 되었습니다. 그래서 기존의 swagger 사이트 서버 앞에 ngnix를 붙이고 그 안에 들어오는 요청에 대해서는 oauth proxy를 통해서 요청이 가도록 구성했습니다.

다음 여정을 준비하며.. 🧘

이런 과정을 통해서 내부 apidoc 사이트가 만들어졌고, 이제 클라이언트/서버 개발자는 단 하나의 사이트 내 링크를 통해서 서로 협업을 하고 질문을 주고 받게 되었습니다. 실제 개발하는데 걸린 시간은 3일 정도 였는데, 많은 리소스를 투입하지 않았고 지금까지 사용하다 보니 부족한 부분과 개선해야 할 부분이 많이 보입니다.

최신의 API swagger 파일을 cron이 아닌 형태로 가져올 수는 없을까?
새 API가 생성 되었을 때, 현재는 volume 에 해당 내용들을 추가하고 API 사이트의 docker를 재실행해야하는데 이 부분을 어떻게 자동화 할 수 있을까?
개발자가 swagger를 만드는 명령어를 일일이 입력해서 생성하고 PR에 올리기 방식으로 하고 있는데, GitHub Actions를 통해서 이 부분을 자동화 할 수는 없을까?
그래도 자체적으로 만든 멋진 API 사이트가 있었으면 좋겠는데?

저와 함께 페이히어의 API 사이트 구축 그리고 다른 개발자의 Productivity 향상에 진심인 백엔드/프론트엔드 개발자를 찾고 있습니다. 프로덕트 외 전사적인 파운데이션 레벨에서 내부 개발자들에 대한 임팩트를 내고 싶은 분들을 적극 찾고 있습니다.

References:

매장의 새로운 미래를 함께 만들어갈 동료를 기다립니다.

채용 분야 확인하기

페이히어 팀

작성자

안성현

CTO