프로젝트 뒤돌아보기 3 - API 명세의 중요성

주의 - 프로젝트를 하고 나서 느낀 개인적인 의견이 담긴 글이니 정확한 정보가 아닐 수도 있습니다.

 

이번에는 더 자세하고 명확한 API 명세에 대해서 얘기해보려 합니다.

이번 프로젝트를 진행하면서 API 명세에 관한 수정사항이 꽤 있었습니다. 또 백엔드 팀이 생각하던 API와 프론트 팀이 생각하던 API의 명세가 달랐습니다.

물론 완벽할 수는 없지만, 앞으로 API 명세에 대해서 진행할 때 개선사항을 적어보려 합니다.

---

기존 API 명세

실제 겪은 문제

1. API 명세가 너무 추상적이었습니다. 친구 요청을 보내면 어떻게 되는지, 친구 요청을 서로 보낼 순 있는지, 친구 요청 시 발생하는 다른 파급 효과들이 무엇이 있는지  등 제약사항 고려가 하나도 없었습니다.

2. 예외 상황을 고려하지 않았습니다.

3. 해당 API가 정말 필요한지, 친구 여러 명에게 보내는 건 필요하지 않은지 등 API에 대한 확장성이나 추가로 필요한 API에 대해 고려하지 않았습니다.

4. 해당 API 명세로 개발할 때 프론트 팀과 다시 한 번 논의해보는 것이 부족했습니다. 그래서 다음에 다시 수정을 한 적이 있습니다.

 

위와 같은 문제점 때문에 이 API에서 친구 요청을 서로 보낼 수 없고 자기 자신에게 친구 요청 보낼 수 없는 등의 제약사항과 입력에 대한 명세를 재정의했습니다. 또 친구 여러 명에게 요청을 보낼 수 있는 API도 추가로 만들었습니다.

---

더 나은 API를 만들기 위해서

앞으로 API 명세를 다시 한 번 한다면

1. API 명세를 작성하기 전에 우리가 만들려는 소프트웨어의 도메인 제약, 정의를 더 자세하게 논의해야겠습니다. 이번 프로젝트에선 친구 요청은 양방향이 가능한지, 타임캡슐은 누구나 볼 수 있는지, 언제나 열 수 있는지, 친구를 차단할 수 있는지 등과 같은 부분이 상세하지 않아 개발할 때 항상 재논의했습니다.

2. 해당 API에 대한 더 자세한 설명과 파급효과, 제약사항에 대해 명세해야겠습니다.

3. 해당 API가 정말로 유의미한가와 이 API 때문에 추가로 필요한 것은 없는지를 고려해야겠습니다.

4. 해당 API를 개발하기 전에 프론트 팀이나 해당 API와 관련 있는 팀과 짧은 논의를 해야겠습니다.

개선된 API 명세

위의 문제점과 개선점을 바탕으로 API 명세를 개선해보겠습니다.

API URL	API 제목	추가 사항	API 입력	API 출력	API 상세 내용
/friends/request	단 건 친구 요청	다 건의 친구 요청을 맺을 수 있는 API 필요 여부 확인	사용자 인증 토큰, 친구를 맺을 대상 아이디	API 작동 성공, 실패 여부	사용자가 친구를 맺을 대상에게 친구 요청을 보낸다. 친구 요청을 수락해야만 친구가 된다. API 요청에 성공하면 친구 요청을 받은 사용자는  친구 요청 알림을 받게 된다.  예외 - 자기 자신에게 친구 요청을 보낸 경우, 서로에게 친구 요청을 보낸 경우면 예외가 발생함.

 

최근에도 기능 개발을 하고 있는데 API 명세를 바탕으로 항상 프론트 팀과 사전에 논의하고 개발을 시작합니다.

확실히 사전에 논의하고 API 개발하니 개발 속도도 더 빠르고 자잘한 수정이나 방향성 오류로 수정하는 상황이 줄어들었습니다.

---

이전보다 명확하고 다양한 사항들을 고려한 API 명세가 된 것 같습니다. 지금 와서 다시 돌아보면 왜 이리 API 명세를 대충했나 싶긴 하더군요...

요근래 CODE COMPLETE를 읽고 있어서 그런지 이 프로젝트에서 제 지난 설계 흔적을 보니 아쉬운 부분이 참 많은 것 같습니다.

아쉬운 부분에 대해서 개선해 나가면서 더 성장할 수 있으니 나름 기쁜 것 같습니다.

다음편은 제약조건에 대해서 다뤄볼까 합니다.