[협업] 프론트엔드 개발자와 협업하기 위한 API 스펙

백엔드 개발자 입장에서 프론트엔드 개발자와 효과적으로 협업하기 위해서는 API 스펙을 미리 작성해서 공유하는 것이라 생각한다. 프로젝트를 진행하다 보니 이런 부분은 선택이 아닌 필수여야 한다고 생각이 들어 정리해보고자 한다.

API 스펙을 만드는 목적은 무엇인가?

왜 API 스펙을 만드는지를 먼저 생각을 해보면:

1. 백엔드+프론트엔드 개발자가 플래닝한 결과에 대해 서로 같은 페이지 (on the same page) 에 있는지 확인하기 위함
2. 백엔드+프론트엔드 개발자가 작업에 대한 소통을 할 때, 레퍼런스가 되는 문서가 필요하기 때문

플래닝 이후에 도출된 세부 작업들을 백엔드는 백엔드끼리, 프론트엔드는 프론트엔드끼리 작업을 하고 나중에 한꺼번에 연동을 해도 되지만, 그렇게 되면 비용이 엄청 비싸진다. 그래서 미리 문서를 만들어두고 어느 정도는 서로가 sync-up 이 된 상태에서 진행하는 것이 좋다고 생각한다.

장점과 단점

프론트엔드 개발자와 협업을 하다 보면 항상 "API 를 어떻게 호출해야 하나요? 요청 body 에는 어떤 값을 넣어서 보내야 하나요? 혹시 Header 에는?" 등의 문의가 많이 들어온다. API 문서가 없는 상태에서 백엔드 개발에 집중을 하다 보면 개발과 스펙 협의를 같이 하게 되면서 업무 집중도가 상당히 떨어지는 것을 느꼈다. 완벽하지는 않지만 최소한의 수준에 부합하는 API 문서를 만들어서 공유를 해보았는데, API 에 대한 문의가 확실히 줄었고, 업무에 좀 더 집중할 수 있는 계기가 되었다. 이는 프론트엔드 개발자에게도 똑같은 pain point 중 하나였는데, 계속 백엔드 개발자에게 API 에 대한 문의를 해야해서 불편하고, 백엔드 개발이 어느정도 마무리가 되어야 프론트 개발도 마무리를 할 수 있어서 dependency 가 있다는 점이 힘들다고 했다.

본 작업 전에 API 문서를 미리 작성하려고 하니 힘든 점도 존재했는데, 일단 상당히 귀찮다. 만들어야 하는 API 가 한두개도 아니고, 각 API 의 요청과 응답에 대해서 상세히 기술해야 한다. 나중을 위해 한다고 생각하고 진행하지만 매번 할때마다 적응 안되는 귀찮음이다. 그리고 요구사항이 다소 자주 변경될 수 있기 때문에 API 문서 자체도 잦은 빈도로 변경될 수 있다.

지금까지의 Best Practice

API 문서를 관리하는 것은 정답이 없는 것 같다. 각자의 환경에 맞게 최적화하여 사용하면 된다고 생각한다. 지금 환경에서는 본 작업 전 백엔드 개발자와 프론트엔드 개발자 간 커뮤니케이션을 위한 목적이 가장 강하다. 그래서 100% 정확하고 엄격하게 작성할 필요는 없다.

API 문서는 플래닝 이후에 바로 진행하고 있고, 별도의 리소스를 할당 받아 작업한다. 대량 1D 에서 2D 정도 산정한다. 플래닝을 하고 나면 만들어야 할 API 목록이 나오게 되고 각 API 에 대해 문서를 작성한다. "사용자"에 대한 예시로 정리하면 다음과 같다.

작업 대상 API 의 목록

카테고리	Http Method	상태	API	설명
사용자	GET	작업 필요	/api/v1/users/{userId}	사용자 ID 기준 조회
사용자	GET	API 작업 완료. 프론트 연동 필요	/api/v1/users	사용자 검색
사용자	POST	프론트 연동 중	/api/v1/users	사용자 생성
사용자	PUT	프론트 연동 완료. 테스트 필요	/api/v1/users/{userId}	사용자 ID 기준 수정
사용자	DELETE	테스트 완료	/api/v1/users/{userId}	사용자 ID 기준 삭제

전체 API 를 하나의 표 형식으로 정리하여 확인한다. 전체 API 목록과 작업 대상인 API 가 현재 어디까지 작업이 되었는지 확인할 수 있다. 하나의 API 에 대해 상세 정리는 다음과 같이 할 수 있다.

상세 API 문서

API /api/v1/users 에 대해서 정리를 한다면:

• 설명
  • (무엇을 하는 API 인지?) 사용자를 검색할 수 있는 API 로 paging 처리가 되어서 반환됩니다.
  • (Validation 은 존재하는지?)
  • (프론트엔드가 알아야 하는 API 로직)
• 요청 (Request)
  • (URL) /api/v1/users
  • (헤더) 없음 (단, GET 이 아닌 다른 유형의 HttpMethod 에서는 포함될 수 있음. 예: requested-by)
  • (PathVariable) 없음
  • (RequestParam) pageNum - 페이지 번호, pageSize - 페이지 당 사용자 명수, userIds: 사용자 IDs, userNames: 사용자 이름s, ...
  • (RequestBody) 없음
• 응답 (Response)

  {
  "success": true,
    "code": 200,
    "message": null,
    "data": {
      "userDtos": [
        {
            "userId": 1,
          "userName": "이름",
          ...
        },
        ...
      ],
        "pagenation": {
          "pageSize: 10,
            "pageNum": 1,
            "nextPage": true,
            "totalElementSize": 123,
            "totalPages": 13,
            ...
      }
  }
  }

마무리하며

rest-docs 나 swagger 를 통한 API 문서 정리도 시도해보았는데, 문서 작성하는데 시간이 너무 많이 소요되고, 실무에서 사용하기가 효과적이지 않았다. Integration Test 를 위해서는 rest-docs 를 작성해두지만 작업 초반에 프론트엔드 개발자들과의 협업을 위한 rest-docs 는 효과적이지 않은 것 같다. 간단하게 이런 문서 형태로 작성해서 공유하는 것이 현재까지는 가장 효과적이었다.

이 문서를 작성하다가 GitBooks? 라는 툴을 알 수 있었는데, 다음 프로젝트에서는 활용해보도록 해야겠다.

• •