API명세서로 협업하기

이번 주제는 개발자가 협업하는 방법에 대해 작성해보려고 한다.

개발자는 혼자 일할수도 있다. 그러나 1인 기업이 아닌 이상 다른 동료들과 협업하며 일을 하게된다.

협업의 대상에는 백엔드 개발자, 프론트엔드 개발자, 디자이너, 퍼블리셔, 비개발부서의 동료들까지 다양하다.

나와 다른 직무(?)를 가진 사람들과 협업하기 위해선 어떤 자세를 가져야하는지 고민하고 찾아보며 정리한 글이다.

 

나는 백엔드개발자이기 때문에, 백엔드 개발자의 관점에서 작성했다.

간단하게 API명세서에 대해 알아보고, 이 명세서를 가지고 어떻게 협업할 수 있는지 생각해보자.

 

1. API명세서란?

백엔드 개발자와 프론트엔드 개발자는 여러가지 방법으로 의사소통을 하며 협업을 진행한다.

그 중 API 명세서를 통한 소통이 아주 중요한데, API명세서는 수많은 회의를 거쳐 설계된 기능을 정리해 놓은 중요한 문서라고 볼 수 있다.

즉, API명세서는 API의 기능, 동작, 사용법 등을 나타낸 문서로, 이 명세서를 잘 이용하면 개발자들은 소통이 더 쉬워지고 빨라질 수 있다.

 

2. API명세서 작성법

API명세서에는 회사에 따라, 작성자에 따라 조금씩 달라질 수 있지만, 보편적으로 아래와 같은 것들이 포함될 수 있다.

• API이름 및 설명
• 기본 정보
  • Host 주소
  • End-Point
  • HTTP Method
• Request
  • Header
  • Body (또는 Query Parameter)
• Response
  • Header
  • Body

이 때, 응답이 여러개로 나뉘는 경우 각각의 응답을 모두 작성해 주는 것이 불필요한 소통을 줄일 수 있기에 더 좋다.

API명세서에 어떤 내용과 얼마나 자세한 내용을 담을것인지를 결정하는 것은 굉장히 애매하고 어려울 수 있다.

이럴 때 참고할만한 기준은 API명세서만 보고도 사용할 수 있는가? 이다.

 

3. 협업하는 방법

타이틀을 협업하는 '방법'이라고 달았지만, 해당 부분은 본인이 속한 팀의 룰이라던지, 개발자가 어떻게 구성되어 있는지 등 상황에 따라 크게 달라질 수 있다.

그러니 큰 틀로만 보고 본인 상황에 맞는 방법을 찾는 것이 중요하다고 말하고 싶다.

---

 

자, 예를 들어 백엔드(서버)개발자와 프론트엔드(클라이언트)개발자가 있다고 생각해보자.

 

[상황1]

백엔드개발자는 API구현과 명세서작성을 끝내고 프론트개발자에게 넘겨주었다.

그런데 프론트개발자가 이렇게 말했다.

"어? 파라미터(속성) 이름이 제가 구현해 놓은 코드와 전부다 다르네요??? 저희 둘 중 하나는 수정이 필요합니다.🤯"

왜 이런 상황이 발생했을까?

바로 API설계가 미리 이루어지지 않았기 때문이다.

이 때 생각해볼수 있는 협업의 자세는 API설계를 먼저 하자이다.

 

프론트엔드개발자는 API규격을 보고 작업을 하게된다.

그렇기 때문에 API명세서가 나중에 나오면 API 구현 기간 동안 작업을 못하거나, 작업을 하더라도 임의로 API주소, HTTP Method, 속성명 등을 사용하다가 나중에 모두 바꿔야하는 상황이 생기게 된다.

 

API설계를 먼저 진행하는 것은 백엔드개발자의 작업에도 긍정적인 영향을 줄 수 있다.

API설계가 진행되지 않은채 백엔드 개발을 진행한다면 개발자의 머릿속에만 존재하는 설계로 개발을 진행하기 때문에, 개발 방향이 틀어질 수도 있고, 놓치는 부분이 생기거나 실수할 여지가 다분해진다.

 

따라서 API 설계를 먼저 진행한 후 구현을 하는 것이 작업 속도와 협업에 있어서 긍정적인 영향을 줄 수 있다.

---

[상황2]

이번엔 백엔드개발자가 API설계를 끝낸 후 프론트개발자에게 먼저 공유를 한 후 API구현을 진행했다.

(이 때 프론트개발자는 바쁜 업무로 인해 API명세서를 한참 후에 보게된 상황이라고 가정한다.)

그렇게 API를 거의 다 구현해갈 즈음 프론트개발자가 이렇게 말했다.

"혹시 A필드는 리스트로 받을 수 있게 수정해주실 수 있으실까요? 또 GET메서드는 body말고 query parameter로 받을 수 있게 수정부탁드립니다.."

이런 상황이 생기면 백엔드개발자는 백이면 백 이런 생각을 할 것이다. '아... 이미 다 만들었는데......🤯'

이 경우에는 어떤 협업의 자세를 생각해볼수 있을까? 바로 API설계 할 때 소통하자이다.

 

위 예시의 경우 백엔드개발자가 혼자 임의로 API를 설계하여 프론트개발자에게 넘겨주었다.

하지만 API는 사용자(대부분 프론트개발자)의 입장도 고려하며 네이밍, 반환타입, 구조, 로직 적용 책임 분배(예를 들면, 정렬을 백에서 할지 프론트에서 할지 등) 등 소통하며 진행해야 하는 부분이 굉장히 많다.

이런 부분들을 소통을 통해 미리 정하고 개발에 들어가는 것이 서로의 시간을 낭비하지 않는 좋은 방법이 될 수 있다!

---

[상황3]

백엔드 개발자는 위의 경험들을 토대로 소통을 통해 사전에 API명세서 작성을 완료하여 프론트개발자에게 넘겨주었다.

그 결과 작업이 빠른 속도로 진행되어 기능을 모두 완성할 수 있었다.

모두가 퇴근한 시간, 백엔드 개발자는 더 좋은 코드를 작성하기 위해 API를 이리저리 수정하고, 배포를 완료하고 퇴근을 했다.

다음날, 프론트엔드 개발자가 배포를 위해 테스트를 진행하는데, 분명 어제까지 나지 않았던 에러가 발생했다.

프론트 : "백엔드개발자님! 혹시 API 수정된 부분이 있나요? 어제까지 잘 되던 기능인데 에러가 나요!"

백 : "아! 제가 어제 일부 수정하고 명세서를 수정을 안했네요! 지금 명세서 수정할게요!"

프론트 : '🤦🏻🤬🤬🤯'

 

이번엔 무엇이 문제였을까?

백엔드개발자가 API수정사항을 공유하지 않고 명세서와 다르게 수정을 했기 때문에 발생한 일이다.

이 때 생각해볼 수 있는 협업의 자세는 API수정사항은 사전에 공유하자이다.

 

API가 수정되면 프론트단의 코드도 얼마든지 수정될 수 있다는 것을 꼭 생각하면서 개발을 진행해야한다.

API는 개발자들간의 약속이기 때문에 수정이 필요하다면 동료들과의 협의를 통해 수정을 진행하거나, 협의하지 못하는 상황이라면 사전에 수정 내용을 공유하고 수정하는 것이 바람직하다.

---

[정리]

개발자가 API 명세서를 통해 협업하는 방법에 대해 간단하게 알아봤다.

이 외에도 각 팀에서 정해진 협업의 방식이 있을 것이고, 본인이 생각하는 더 중요한 협업의 자세가 있을 것이다.

어떤 방식이든 본인에게 맞는, 팀에게 맞는 것을 찾아가면 된다.

하지만 위 세 상황에서도 알 수 있듯 제일 중요한 요소는 '소통'이라고 생각한다.

유능한 개발자 100명이 모여도 팀으로써 소통이 되지 않는다면 효율적인 작업은 불가능할것이다.

 

4. 마무리

API를 통한 협업 외에 다른 협업의 자세를 간단하게 작성해보자면..(실제 경험에 따른 주관적인 것)

한 프론트개발자가 나에게 와 "ㅇㅇ님 이 API 이렇게저렇게 수정해주세요 (쌩~)" 하고 가버려 굉장히 당황스러웠던 적이 있다.

앞뒤 상황 설명 없이 수정요청을 하는 바람에 직접 해당 개발자를 찾아가 정확한 요구사항을 다시 묻는 비효율적인 작업을 했다.

또한 설명을 듣는데, 본인의 입장에서만 설명을 하는 통에 이해하지 못한 부분을 계속 다시 묻는 상황이 발생했다.

나는 이 때 이런생각을 했다. '나도 이렇게 내 위주로 생각하고 말을하나? 앞으로 상대방의 입장에서 생각하고 말해야겠다.'

 

대게 사람들은 같은 일을 해나갈 때 내가 아는 것을 상대방도 안다고 생각하고 일부 설명을 제외하거나, 요약해서 말을 한다고 한다.

요약해서 필요한 것만 이야기 하는 것은 물론 좋은 방식이지만, 서로 관심사가 다른(백-프론트)상황이라면 상대방의 입장에서 소통을 하는 것이 바람직하다고 생각한다.

 

위와 같은 경험들이 하나 둘 쌓이고 자세를 고쳐나간다면 언젠가 같이 일하고 싶은 동료로 기억되지 않을까 싶다!

그런 날이 오길 기대하며 역량을 쌓아나가야지.