늦었지만 써보는 2023 인프콘 후기 정리 - 1. API First Design

2023 인프콘 참여

운이 좋게도 작년 블로그 이벤트에서 당첨된 인프콘 티켓을 통해서 2023 인프콘 참여를 했었습니다.

들은 세션에 대해서 내용정리를 한게 있었는데 이제야 꺼내서 정리해봅니다.

 

본 포스트는 1개의 세션내용을 포함하고 있습니다.

오늘도 여러분들의 API는 안녕하신가요? : API First Design과 Code Gen 활용하기

API 사용에 있어서 아래와 같은 문제들을 개발자들은 다루고 있습니다.

1. 어떻게 API를 설계해야할지, 어떤 형식으로 만들어야 할지?

2. API 코드 수정 이후에 변경된 API 명세를 API 문서에 정확히 반영을 하고있는지?

 

이런 질문에 좋은 대답을 하기 위해서는 실제로 어떤 방식으로 API 문서가 관리되는지가 중요할것 같습니다.

 

API를 잘 관리하지 않으면 생기는 문제

발표에서도 나왔듯

팀 적으로 API를 어떻게 관리 할지에 대한 고민 없이 API를 작성하고 문서를 다루게 되면 아래와 같은 순서로 관리를 할 확률이 큽니다.

일반적으로 발생하는 API 및 API 문서관리의 순서

1. API 설계 문서를 작성하고

2. API 문서에 따라 코드를 구현하고

3. 문서화 도구를 이용해서 문서화를 하고

4. API 문서를 전달합니다.

 

언뜻 봐서는 문제가 없어보이지만, 실제로 해당 방식으로 작업을 하게 되면 API 요구사항이 변경 될 시에 

2,3,4 번을 동일하게 다시 진행해야합니다.

그것을 계속 반복하다보면 아래와 같은 문제가 발생합니다.

 

1. 일관성 없는 API 설계 문서

1. 일관성 없는 API 설계문서

하나의 통일된 방식이 아니라 사람마다 각자 다른 문서가 발생할 수 있습니다.

그러면서 API 설계문서가 일관성이 사라지게 되죠.

그러면 그 문서들을 관리하기 위한 비용이 증가하게 됩니다.

 

그리고 또 다른 문제가 발생할 수 있는데요. 

바로, API 문서를 2번 작성해야해서 번거로워 진다는 것입니다.

 

2. API 문서를 2번 작성해야 한다는 것

API 설계 문서와 API 문서를 모두 만들어야합니다.

그러면 아래와 같은 문제가 발생할 수 있죠.

이 두 가지 중에 무엇이 믿을만한 API 문서인가?

정확한 API를 확인하기 위해서 추가적인 시간이 들것입니다.

 

그리고 또 다른 문제도 있습니다.

 

3. 최종 API문서에 반영이 되지 않는것.

요구사항의 변경으로 API 문서 및 코드가 변경이 되었습니다.

그런데 3번 문서화 도구를 이용한 문서화 작업이 일정이나 개인의 까먹음등을 이유로 작성하지 않거나 구두로 전달이 된다면?

시간이 지나게 되면 다른 API를 쓰는 개발자와 문서가 아닌 다른 방법으로 추가 소통이 필요하게 됩니다.

 

이런 문제들을 방지하기 위해 나온것이 API First Design이다 라고 할 수 있습니다.

 

API First Design의 장점

API First Design은 마치 기계들간에 계약서를 만들어 이 계약대로 요청을 주고 받는 형식과 동일합니다.

이를 더 잘 해주기 위해서 OPEN API Specification (OAS)를 활용할 수 있습니다.

OAS는 이미 정해진 룰이 있어서 그것을 따르기만 하면 됩니다.

포맷은 아래와 같습니다.

OPEN API Specification의 포맷

그리고 이 문서만 작성하게되면 실제 코드의 포맷과 문서를 아래와 같은 도구들을 통해서 자동으로 생성할 수 있게됩니다.

OPEN API Specification 사용한 도구들

 

이를 사용하면 처음에 제시했던 API 작성 방식을 아래와 같이 변경할 수 있습니다.

1. OPEN API 명세서 설계

2. 반복적 설계

3. OPEN API 도구 활용 & 구현

4. API 문서 전달

API FIRST Design : OAS를 활용한 API 개발 프로세스

 

이를 통해서 위에서 언급한 문제들을 해결할 수 있습니다.

1. 일관성 없는 API 설계 문서 => 일관성 있는 API 설계 문서

하나의 문서로 API를 관리하여 일관성이 생김

 

3. 코드 변경사항이 최종 API 문서에 반영되지 않는 문제 => API 명세서 자체가 변경되어 별도 문서 업데이트 불필요

API 명세서 하나만 관리하고 그것으로 문서 생성을 자동화하므로 문서 업데이트 불필요

 

추가로 아래와 같은 장점들을 더 얻을수도 있습니다.

 API 변경에 대한 버전 히스토리를 관리할 수 있다는점

OAS로 API 버전 히스토리 관

2공통의 API 문서를 통해 함께 협업 할 수 있다는점

공통의 API 문서를 통해 협업 가능

이해관계자들과 함께 풍성한 내용이 담긴 API를 만들 수 있다는점

 

---

세션은 위 내용을 포함하고 있었습니다.

내용을 다시 정리해보면서 현재 제 회사에서도 동일하게 적용되고 있는 부분이 있고 놓치고 있는 부분이 있어서 그 부분들을 정리하기에 좋았던것 같습니다.

실제로 회사에서 해외 연구소 분들이 Frontend를 담당하기로 하면서 위와 같은 논의가 필요하고
발생하는 여러 문제점들을 해결하기 위해서 API First Design을 도입을 하게 되었는데요.

이 과정에서 놓치고 있던 부분은 아래와 같습니다.

 

실제 우리 부서가 API First Design을 도입함에 있어서 놓친 부분

1. OAS에 Versioning을 따로 변경하지 않았다는 점 

제품의 버전도 정해져는 있는데, OAS에는 명시를 하지 않아서 계속 0.0.0 버전으로 관리되고 있었습니다.

까먹고 있던 부분이었는데 다시 내용을 보다보니 이 부분을 변경해야한다는 게 생각났네요

이 부분도 관리해야함을 까먹고 있었네요 ㅠ

2. Swagger를 통해서 API 문서, Codegen 뿐만이 아니라 다른 기능도 지원한다는 사실

여러 기능들을 지원하는 Swagger

필요 한 것 중에 API Testing이나 Mocking 같은게 있는데 이를 활용하지 않고 있었네요

회사에 돌아가면 추가할 수 있을지 확인 해 봐야 겠습니다 ㅎㅎㅎ 

 

3. OPEN API 문서 설계 단계중 1단계를 제외하고 진행하고 있었다는 사실

1번 단계가 OPEN API 명세서를 이해 관계자와 같이 논의하고 작성할 수 있으면 두번 일 하는것 없이 좋을것 같은데, 회사에서 사용하고 있는 Confluence에 API 문서를 만들어 놓고 그것을 토대로 논의를 하고 있었네요.

그 부분을 없애고 다음부터는 YAML 파일 자체로 논의를 하면 두번 일 하는것 없이 더 명확하게 논의를 할 수 있을것 같습니다 ㅎㅎㅎ

 

이렇게 예전 세션을 다시 리뷰하면서 놓치고 있었던 부분까지 다시 확인 할 수 있어서 포스팅이 더 풍성해진것 같네요.

 

다음 포스트는 또 다른 세션으로 다시 찾아오도록 하겠습니다.