본 시리즈의 글들은 F-Lab 커뮤니티에서 진행한 소규모 컨퍼런스에서 발표한 내용입니다.
좋은 HTTP API란 무엇일까?
이러한 질문에 대답하기 전, 기본으로 돌아가보자.
HTTP API 란 무엇일까? 필자가 생각하는 HTTP API란 다음과 같다.
특정 자원에 접근, 동작을 기대하는 것
URI를 통해 자원을 식별하여 접근하며, HTTP Method를 통해 기대하는 동작을 명시하는 것이다.
여기서 중요한 점은 동작을 기대한다는 것인데, 이는 강제성이 없음을 의미한다.
다시 돌아가서, 좋은 HTTP API란 무엇일까?
OpenAPI, Swagger의 best practice 혹은 다른 페이지에서 말하는 좋은 HTTP API에는 몇가지 법칙이 있다.
예를 들면 다음과 같다.
- 명사로 작성되어야 하며 컬렉션일 경우 복수형이여야 한다.
- URI 경로에는 소문자가 적합하다.
하지만 과연 이런 약속들을 잘 지킨다고 좋은 HTTP API가 될까? 그건 아니라고 생각한다.
그럼 뭐가 좋은건데?
좋은 HTTP API를 구분하는 기준은 각자 다르겠지만, 고민해본 결과 다음과 같은 결론을 내렸다.
이 중, 리소스의 식별에 대해 예시를 들어보았다.
올바른 Method를 사용하는 것이 덜 중요한 것이 아니고, 본 포스트의 주 내용이 리소스의 식별이라는 것이다.
F-Lab의 커뮤니티는 다음과 같이 구성된다. 워크스페이스 하위에 채널들이 있고, 각 채널마다 멤버들이 존재한다. 신입 개발자 Kong씨는 위와 관련된 HTTP API를 설계하는 미션을 받았다.
Kong씨는 아무 생각없이 설계를 진행했다. 워크스페이스 밑에 채널이 있다. 채널 밑에는 멤버가 있다. 일단 CRUD 역할을 하는 것들을 만들어봤다.
이제 각 채널에 속한 멤버를 호출하는 API를 만들었다.
만들고보니 뭔가 이상하다. F-Lab 커뮤니티에 존재하는 모든 멤버를 보기 위해선 어떻게 만들어야 할까?
Kong씨는 머리를 쥐어 짜 위 두가지 방법을 생각해냈다.
첫번째의 경우 모든 채널의 멤버라는 의미기에 직관적으로 보기 힘들다는 느낌을 받았고, 두번째의 경우 계층 구조가 지켜지지 않아 혼란을 가중시킬 것 같았다.
이러한 경우엔 어떻게 설계해야 보기 좋을까?
위 예제를 통해 필자가 말하고자 하는 건 리소스의 식별이 중요하다는 것이다.
리소스의 식별
첫 단계에서 리소스를 식별할 때로 돌아가보자.
워크스페이스 밑에 채널들이 있고, 그 밑에 멤버가 있다.
과연 이게 맞을까?
다시 생각해보면 멤버는 워크스페이스에 있고, 각 멤버가 채널에 참여하는 형태이다.
그렇다면, 왼쪽과 같이 채널 밑에 멤버가 있는 것이 아닌 워크스페이스 밑에 있는 것으로 식별할 수도 있을 것이다.
이러한 식별을 통해 다시 API를 설계해보면 아래와 같이 훨씬 직관적인 API를 도출해낼 수 있다.
이제 F-Lab 커뮤니티에 존재하는 모든 멤버들을 볼 수도 있고, query string을 통해 채널을 입력받아 필터링을 할 수도 있다.
결론
멘토링을 진행하며, 멘토님께 많은 얘기를 들을 수 있었다.
본인만의 원칙을 확립하고 따라라.
이 원칙을 기반으로 선택의 이유를 만들어라.
결국, 자신만의 기반을 만들어야 한다는 것이고, 이 기반을 확립하는데는 많은 고민이 필요하다고 생각한다.
위 예시를 마치며 낸 결론이 반드시 옳다는 것도, 좋다는 것도 아니다.
다만, 나라는 개발자가 어떠한 원칙으로 설계했는지에 대해 고민하며 준비해보았다.
개발 시장에 뛰어드는 모든 개발자가 주어진 지식을 정제하고, 고민하며 자신만의 원칙을 세워가는 멋진 개발자가 되기를 바라면서!
