라이징 프로그래머2의 4주차 과제 중 두번째인 API 명세서 작성을 진행해보았다. 직전 포스팅에서 REST API가 무엇인가, 에 대해서 공부를 하였다면 이번엔 직접 URI 및 요청과 응답, HTTP Method까지 모두 설계해보았다.

스트리밍 서비스, Melon!

내가 선택했던 클론 코딩 서비스는 Melon이었다. 본디 음악을 사랑(?)해왔기 때문에 선택에는 그리 오랜 시간이 걸리지 않았다. 하지만 REST API의 URI를 설계하면서 계층간 관계에 대해서 굉장히 많이 고민하는 시간이 필요했다. 각각의 요소들을 어떤 식으로 관계를 맺어줄 것인지에 대해서.

계속해서 과제를 진행하다보니 점점 규모가 커지던 데이터베이스는 테이블이 15개가 넘어가는 기염을 토했다. (물론 모두 나의 머릿속에서 나온 것들을 구현한 것이므로, 지극히 주관적인 데이터베이스(?)라는 것을 미리 강조하도록 하겠다)

처음엔 액셀에다 작업을 했었다. 그러다보니 불편한 점이 이만저만이 아니었고, 무엇보다 공유를 해서 구성원들과 함께 열람하여 피드백을 받는 것이 쉽지 않았다. 그래서 도중에 구글 스프레드 시트를 사용하기 시작했다.

가장 먼저 했던 일은, 기능을 구현할 수 있냐 없냐를 떠나서 일단 내가 생각하는 모든 기능들을 최대한 생각해내어 Index라는 이름 아래에 기록했다. 단순하게 생각해도 60가지 이상의 기능들이 뽑혀져 나왔다(구현은 저 멀리..). 애초에 목적은 최대한 실제 프로덕트에 근접하게 기능을 작성하고 명세를 통해서 어떻게 API를 사용하는지 알려주는 것이라고 생각했다.

각각의 기능들은 최대한 REST API의 URI 설계 규칙에 맞게 URI를 설계하려고 노력했는데 잘 되었는지는 잘 모르겠다.

다음은 직접 설계한 API 명세서의 URI중 일부이다.

특히, 유저의 로그인과 로그아웃과 같은 URI의 설계가 굉장히 고민이 많이 되었다. 로그인은 생성(POST)도 아니고 수정(PATCH, PUT)도 아니고 삭제(DELETE)는 더더욱 아니기에 처음엔 GET METHOD로 설계했었다.

그러나 피드백 과정에서 유저가 로그인을 하면 토큰을 발행한다는 개념으로 접근하여, POST METHOD가 적합하다고 판단되어 수정되었다.

응답은 클라이언트가 접근하는 화면에 필요한 모든 정보를 다 담으려고 노력했다.

다음은 명세서의 일부이다. 가능한한 모든 정보를 상세히 기재해놓으려고 했다. 클라이언트와 서버가 소통하는 통로가 명세서이기 때문에, 정확하고 확실한 정보를 전달해야하기 때문이다(하지만 그 속에서도 구멍은 존재하기 마련이다).

물론 그와중에도 놓친 부분들이 많아서, 중간중간에 계속해서 구현 로직과 명세서에 변화가 있었다. 추후에 협업을 하게 된다면 이러한 부분들 때문에 여러 이슈가 발생할 것 같다는 생각이 들었다. 따라서 한번에 바로 완벽한 설계를 할 수는 없으나, 가능한한 초기 설계를 견고하게 하는 것이 좋을 것 같다.

물론 변화는 어디에나 있기 마련이므로 이 부분은 유념하도록 하자!

참고자료

• 만약 REST API에 대해서 궁금하다면 직전 포스팅을 참고하도록 하자.