[웹 API 디자인] 2. 명사는 좋고, 동사는 나쁘다

명사는 좋고, 동사는 나쁘다

첫 번째로, 실용적인 RESTful 디자인에서 가장 중요한 원칙은 간단한 것을 간단하게 유지하는 것입니다.

단순하고 직관적인 기본 URL을 유지하세요

기본 URL은 API의 가장 중요한 디자인 어포던스(design affordance)입니다. 간단하고 직관적인 기본 URL 디자인은 API 사용을 쉽게 만듭니다.

어포던스는 문서화가 필요하지 않고 어떻게 사용해야 하는지를 전달하는 디자인 속성입니다. 문을 열 때 당기는지 밀어야 하는지를 전달하는 문손잡이의 디자인이 예시입니다. 다음은 디자인 어포던스와 문서화 간의 충돌 예시입니다. 이것은 직관적인 인터페이스가 아닙니다!

Web API 디자인에서 우리가 사용하는 중요한 시험 방법 중 하나는, 자원(resource) 당 기본 URL이 두 개만 있어야 한다는 것입니다. 간단한 객체나 자원, 예를 들어 개(dog)를 기반으로 API를 모델링하고 Web API를 생성해 보겠습니다.

첫 번째 URL은 컬렉션(collection)을 위한 것이고, 두 번째 URL은 컬렉션 내 특정 요소를 나타냅니다.

/dogs       /dogs/1234

이렇게 단순화하면, 기본 URL에서 동사(verb)를 사용하지 않도록 강제할 수도 있습니다.

기본 URL에서 동사를 제거하세요

많은 Web API들은 URL 디자인에 방법(method) 기반 접근법을 사용하여 시작합니다. 이러한 방법 기반 URL들은 때로는 동사를 포함하고 있는데, 때로는 시작부분에 위치하고 때로는 끝부분에 위치합니다.

우리가 예로 들어본 개(dog)와 같은 리소스를 모델링할 때, 항상 고려해야 할 것은 독립적인 하나의 객체가 아니라, 주인, 수의사, 끈, 사료, 다람쥐 등과 같이 연관되고 상호작용하는 리소스들이 있습니다.

개(dog) 세상에서 모든 객체를 다루기 위해 필요한 메소드 호출에 대해 생각해보세요. 우리 리소스에 대한 URL은 다음과 같아 보일 수 있습니다.

이것은 걷잡을 수 없는 것입니다. 곧 URL의 긴 목록이 생기고 개발자가 API를 사용하는 방법을 배우기 어렵게 만들기 때문에 일관된 패턴이 없습니다.

HTTP 동사를 사용하여 컬렉션과 엘리먼트를 조작하세요

개(dog) 자원에 대해 두 개의 명사 라벨을 사용하는 두 개의 기본 URL이 있으며, 이를 HTTP 동사로 조작할 수 있습니다. HTTP 동사는 POST, GET, PUT, DELETE입니다. (CRUD (Create-Read-Update-Delete) 약어로 매핑되는 것으로 생각합니다.)

두 개의 리소스 (/dogs 및 /dogs/1234)와 네 가지 HTTP 동사로 인해 개발자가 직관적으로 사용할 수 있는 다양한 능력을 가지게 됩니다. 강아지 자원을 예로 들어 설명한 차트를 확인해보세요.

Resource	POST(Create)	GET(Read)	PUT(Update)	DELETE(Delete)
/dogs	Create a new dog	List dogs	Bulk update dogs	Delete all dogs
/dogs/1234	Error	Show Bo	If exists update Bo / If not error	Delete Bo

API의 동작 방식을 이해하기 위해 개발자들이 차트를 필요로 하지 않을 수 있다는 것이 핵심입니다. 개발자들은 문서 없이도 API를 시험하고 학습할 수 있습니다.

요약하자면 다음과 같습니다:

• 리소스당 두 개의 기본 URL을 사용하세요.
• 기본 URL에서 동사를 사용하지 마세요.
• HTTP 동사를 사용하여 컬렉션과 요소를 조작하세요.