개발자
보통 rest api 네이밍 규칙에서 단수형보다 복수형을 사용하라고 하는데 단어 자체가 복수형일 경우에는 어떻게 하나요? 예를 들어서, 단어 data 같은 경우에는 data 자체가 복수형이니 /datas라고 하기도 좀 그렇고, 또 한편으로는 영어시험도 아닌데 팀끼리 컨벤션만 맞추면 다소의 문법오류는 괜찮지 않나? 하는 생각도 듭니다. 어떤게 더 나은 방향일까요?
답변 1
인기 답변
URL에 복수형 명사를 사용하는 것은 REST API를 설계할 때 매우 널리 통용되고 있는 명명 관행(naming convention)입니다. 그리고 사람들이 보통 잘 설계되었다고 평가하는 REST API는 이러한 명명 관행을 충실하게 따르고 있는 경우가 많은데요. 명명 관행을 잘 따르면 굳이 문서를 꼼꼼이 읽어보지 않더라도 쉽게 호출할 수 있어서 사용자 경험이 매우 좋기 때문입니다. 반면에 이러한 기본적인 설계 관행을 따르지 않는 REST API는 클라이언트 입장에서 쓰기가 참 고통스럽습니다. 이 것은 비단 외부에 공개된 REST API에만 국한된 것은 아닙니다. 회사 내부적으로만 사용되는 REST API의 경우에도 정해진 네이밍 규칙이 없거나 네이밍에 일관성이 없다면 조직 간 커뮤니케이션이 매우 비효율적이게 되며, 결국 곧 개발 생산성 저하로 이어질 수 있습니다. 말씀하신 것처럼 일부 영단어들은 단복수형의 구분이 없어서 REST API를 설계할 때 고민이 될 수 있습니다. 그런데 그러한 단어들은 대부분 추상 명사나 집합 명사와 같이 영어 문법적으로 셀 수 없으며 애초에 정보화 자체가 난해한 컨셉이거나 데이터베이스에 저장하기 부적합한 경우가 많습니다. 관련해서 한 가지 팁을 드리면 이러한 불가산 명사를 비슷한 뜻을 가진 가산 명사로 대체할 수 있는 경우도 많습니다. 예를 들어, 음원 서비스의 REST API를 설계한다면 셀 수 없는 `music`이라는 단어를 선택하여 어색하게 `/musics`라고 하는 것보다는 `song`이라는 단어를 선택하여 `/songs`라고 하는 것이 더 나을 것입니다. 다른 예로, 직원 관리를 위한 REST API라면 불가산 명사인 `/staffs` 보다는 가산 명사인 `/employees`가 더 적합하겠죠? 예를 들어 주신 data와 같이 (또는 info, information 등등) 너무 광범위한 의미를 가진 단어는 REST API를 설계하실 때 피하시는 게 좋습니다. 왜냐하면 URL만 보고 바로 어떤 데이터를 위한 API인지 알기 힘들기 때문입니다. 예를 들어, `GET data/1`이 무엇을 제공하는지, `DELETE information/2`가 무엇을 삭제할지 클라이언트 입장에서 예상하기가 어렵습니다. 해당 API가 다루고 있는 데이터를 좀 더 구체적으로 한정지을 수 있는 더 나은 영단어가 분명히 있을 것입니다. 데이터 모델링을 할 때, DB 테이블의 이름을 `data`로 잘 짓지 않는 것과 같은 이치라고 보시면 될 것 같습니다.
익명
작성자
2024년 01월 29일
오 감사합니다! 궁금한 내용이 해결되었어요!
지금 가입하면 모든 질문의 답변을 볼 수 있어요!
현직자들의 명쾌한 답변을 얻을 수 있어요.
이미 회원이신가요?
커리어리 AI 봇
GPT가 달아주는 답변입니다.
2024년 01월 26일
REST API 네이밍에 대한 궁금증은 이해할 수 있습니다. 사실, 이와 같은 경우에는 정답이 없고 팀의 기준과 컨벤션에 따라 결정하게 됩니다. "데이터"라는 단어 자체가 이미 복수형이므로 "/data"를 사용하는 것이 일반적입니다. "/datas"는 올바른 복수형 표현이 아니기 때문에 보통 추천하지 않습니다. 디자인 원칙에서 중요한 부분 중 하나는 일관성입니다. 팀 내에서 적용하려는 REST API 명명 규칙이 무엇인지 명확하게 정해야 합니다. 따라서, 영어 문법 오류보다는 URL 패턴의 일관성을 유지하는 것이 가장 중요합니다. 예를 들어, "/products", "/users", "/categories" 등과 같은 복수형 리소스 이름을 사용한다면, "/data"도 마찬가지로 복수형으로 처리하는 것이 좋습니다. 마지막으로, 패턴과 컨벤션을 문서화하여 모든 팀 멤버가 이해하고 따르도록 하는 것도 매우 중요합니다. 이렇게 하면 API의 설계와 유지 관리가 더욱 용이해집니다.
지금 가입하면 모든 질문의 답변을 볼 수 있어요!