[웹 API 디자인] 3. 복수형 명사와 구체적인 이름 사용

복수형 명사와 구체적인 이름 사용

URL의 명사를 선택하는 방법을 알아봅시다.

리소스 이름에 단수 명사를 사용할지, 복수 명사를 사용할지 선택해야 할까요? 인기 있는 API에서는 둘 다 사용하는 것을 볼 수 있습니다. 몇 가지 예시를 살펴보겠습니다.

Foursquare      GroupOn     Zappos
/checkins       /deals      /Product

RESTful API를 사용할 때 대부분의 사람들이 먼저 하는 것은 GET 요청이기 때문에 복수 명사를 사용하면 읽기 쉽고 직관적으로 느껴진다고 생각합니다. 그러나 무엇보다도 일관성 있는 방식으로 작성해야 합니다. 어떤 리소스는 단수 명사를 사용하고 다른 리소스는 복수 명사를 사용하는 혼합된 방식은 피해야 합니다. 일관성 있는 방식으로 작성하면 개발자들은 API를 사용하는 방법을 배우면서 메소드 호출을 예측하고 추측할 수 있습니다.

구체적인 이름이 추상적인 이름보다 좋습니다.

순수한 추상화를 달성하는 것은 때로 API 설계자의 목표가 됩니다. 하지만 그 추상화는 개발자에게 항상 의미 있는 것은 아닙니다.

예를 들어, 여러 형태의 콘텐츠에 액세스하는 API를 생각해 봅시다 - 블로그, 비디오, 뉴스 기사 등.

우리 예시에서 /items 또는 /assets와 같이 모든 것을 가장 높은 수준의 추상화로 모델링하는 API는 개발자가 이 API로 무엇을 할 수 있는지 알기 위한 구체적인 그림을 제시할 기회를 상실합니다. 블로그, 비디오, 뉴스 기사와 같은 리소스가 명시적으로 나열된 API가 더 흥미롭고 유용합니다.

추상화 수준은 상황에 따라 다릅니다. 또한 관리 가능한 리소스 수를 노출하려고 노력해야 합니다. 구체적인 이름을 사용하고 리소스 수를 12개에서 24개 사이로 유지하도록 노력하세요.

요약하자면, 직관적인 API는 단수 명사 대신 복수 명사를 사용하고 추상적인 대신 구체적인 이름을 사용합니다.