API First Design

API First Design

프론트엔드와 백엔드가 API 설계를 가장 먼저 함께 진행하고, 해당 API를 중심으로 시스템을 구축해 나가는 개발 방식

API First Design은 단순히 API를 먼저 만든다는 의미를 넘어서, “API를 기준으로 협업의 기준과 흐름을 맞추는 개발 문화” 에 가까움

일반적인 서비스 개발 흐름에서의 문제

기존 서비스 개발 방식은 다음과 같은 흐름을 따름

1. 백엔드 개발자가 기획서를 기반으로 API를 설계함

   1. 백엔드는 API 설계과정에서 많은 고민 필요

   2. 프론트엔드는 백엔드의 API 설계가 끝날 때까지 대기하게 됨.

   3. API가 전달되었지만, 실제 화면 구현 과정에서 불명확하거나 누락된 부분이 드러남

   4. 그 결과 다시 백엔드와 수정 협의 → 재작업 → 반복, 커뮤니케이션 비용 증가

2. 만들어진 API를 프론트엔드가 전달 받아 어떻게 API를 매핑하고 활용할지 고민 후 설계

   1. 프론트엔드는 명세에 맞지 않거나 부족한 데이터를 짜집기하거나 가공하면서 개발을 진행하게 됨

   2. 시간이 지날수록 프론트와 백엔드는 서로 다른 맥락 속에서 개발을 이어가게 되고, 유지보수는 점점 어려워짐

이러한 문제들을 줄이기 위한 해결책이 API First Design

장점

• 병렬 개발 가능: 백엔드가 API를 개발하기 전에도, 프론트는 Mock API 기반으로 작업을 시작할 수 있음

• 커뮤니케이션 효율화: 초기 설계를 함께 하므로 이후 불필요한 협의가 줄어듦

  • 함께 만들게되니 기준이 생기고 시간을 아낄수 있게됨

• 프론트엔드 생산성 향상: 실제 화면 흐름에 맞춘 API 설계로 추가 가공 없이 바로 사용 가능

상대적으로 프론트엔드가 API를 사용해서 화면을 구현하다보니 어떤 API가 어떻게 쓰이고 필요한지 조금 더 빨리 파악하거나 잘알고있을 가능성이 높음, 그래서 먼저 적극적으로 요청하거나 조율해서 협의하게됨

주의할점

• 처음부터 완벽한 API를 설계하기는 어려움. 실무에서는 변경이 잦기 때문에, API는 유연하게 유지해야 함

• 변경 사항에 대한 기록과 공유가 중요함. 명세의 이력 관리가 없으면, 시간이 지난 뒤에 변경 맥락을 알기 어려움

  • 자동 문서화 및 코드 생성 도구 연계 가능: 예: OpenAPI → Swagger → 코드 생성

• API 명세 변경 시 자동 반영 체계 필요. 그렇지 않으면 문서와 실제 코드가 어긋날 수 있음

OpenAPI

RESTful API를 정의하기 위한 가장 널리 사용되는 스펙 중 하나.

• Swagger: OpenAPI 기반으로 API 명세서를 시각화하고 테스트할 수 있는 도구

• openapi-generator:

  • OpenAPI 명세를 기반으로 실제 API 클라이언트 코드, 타입, 문서 등을 자동 생성

  • 변경사항이 반영되면 코드도 자동으로 업데이트되므로 생산성과 일관성 확보 가능