개발자

REST API 규칙 궁금합니다.

2024년 01월 26일조회 878

보통 rest api 네이밍 규칙에서 단수형보다 복수형을 사용하라고 하는데 단어 자체가 복수형일 경우에는 어떻게 하나요? 예를 들어서, 단어 data 같은 경우에는 data 자체가 복수형이니 /datas라고 하기도 좀 그렇고, 또 한편으로는 영어시험도 아닌데 팀끼리 컨벤션만 맞추면 다소의 문법오류는 괜찮지 않나? 하는 생각도 듭니다. 어떤게 더 나은 방향일까요?

이 질문이 도움이 되었나요?
'추천해요' 버튼을 누르면 좋은 질문이 더 많은 사람에게 노출될 수 있어요. '보충이 필요해요' 버튼을 누르면 질문자에게 질문 내용 보충을 요청하는 알림이 가요.
profile picture
익명님의 질문

답변 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`로 잘 짓지 않는 것과 같은 이치라고 보시면 될 것 같습니다.

profile picture

익명

작성자

2024년 01월 29일

오 감사합니다! 궁금한 내용이 해결되었어요!

지금 가입하면 모든 질문의 답변을 볼 수 있어요!

현직자들의 명쾌한 답변을 얻을 수 있어요.

또는

이미 회원이신가요?

AI 답변
커리어리 AI 봇 프로필 이미지

커리어리 AI 봇

GPT가 달아주는 답변입니다.

2024년 01월 26일

REST API 네이밍에 대한 궁금증은 이해할 수 있습니다. 사실, 이와 같은 경우에는 정답이 없고 팀의 기준과 컨벤션에 따라 결정하게 됩니다. "데이터"라는 단어 자체가 이미 복수형이므로 "/data"를 사용하는 것이 일반적입니다. "/datas"는 올바른 복수형 표현이 아니기 때문에 보통 추천하지 않습니다. 디자인 원칙에서 중요한 부분 중 하나는 일관성입니다. 팀 내에서 적용하려는 REST API 명명 규칙이 무엇인지 명확하게 정해야 합니다. 따라서, 영어 문법 오류보다는 URL 패턴의 일관성을 유지하는 것이 가장 중요합니다. 예를 들어, "/products", "/users", "/categories" 등과 같은 복수형 리소스 이름을 사용한다면, "/data"도 마찬가지로 복수형으로 처리하는 것이 좋습니다. 마지막으로, 패턴과 컨벤션을 문서화하여 모든 팀 멤버가 이해하고 따르도록 하는 것도 매우 중요합니다. 이렇게 하면 API의 설계와 유지 관리가 더욱 용이해집니다.

목록으로

지금 가입하면 모든 질문의 답변을 볼 수 있어요!