[웹 API 디자인] 4. 연관성 단순화 - 복잡성은 ‘?’ 뒤로 숨겨두기

연관성 단순화 - 복잡성은 ‘?’ 뒤로 숨겨두기

이 섹션에서는, 자원 간의 연관성 및 상태 및 속성과 같은 매개 변수를 처리할 때 API 디자인에 대한 고려 사항을 살펴봅니다.

연관성

리소스들은 대부분 다른 리소스와의 관계를 가집니다. 웹 API에서 이러한 관계를 어떻게 간단하게 표현할 수 있을까요?

우리가 이전에 모델링한 API “명사는 좋고, 동사는 나쁘다”를 다시 살펴보겠습니다. 이 API는 우리의 개(dog) 리소스와 상호 작용합니다. 기억해봅시다. 두 개의 기본 URL이 있었습니다. /dogs와 /dogs/1234입니다.

우리는 리소스와 컬렉션을 조작하기 위해 HTTP 동사를 사용하고 있습니다. 우리의 개(dog)는 주인에게 속합니다. 특정 주인에게 속한 모든 개를 가져오거나 그 주인을 위해 새로운 개를 만들려면 GET 또는 POST를 사용하세요.

GET /owners/5678/dogs
POST /owners/5678/dogs

이제, 관계는 복잡해질 수 있습니다. 주인은 수의사와, 수의사는 개(dog)와, 개(dog)는 사료와 같은 관계를 가질 수 있습니다. 이러한 관계들을 URL로 이어 붙여 5~6단계까지 이루어진 URL도 볼 수 있습니다. 그러나 기본키(Primary key)를 갖고 있으면, 일반적으로 위 단계의 URL이 필요하지 않기 때문에 특정 객체를 이미 갖고 있는 경우 위의 수준을 포함시킬 필요가 없습니다. 다시 말해, 위에서 언급한 /resource/identifier/resource보다 URL이 더 깊어지는 경우는 많지 않아야합니다.

’?’ 뒤로 복잡한 내용을 숨기세요

대부분의 API는 리소스의 기본 수준 이상의 복잡성을 가지고 있습니다. 이러한 복잡성에는 업데이트, 변경, 쿼리할 수 있는 많은 상태 및 리소스와 연결된 속성이 포함됩니다.

개발자가 기본 URL을 사용하기 쉽게하려면 HTTP의 물음표 뒤에 선택적인 상태 및 속성을 놓으십시오. 예를 들어, 공원에서 달리는 빨간 개를 모두 얻으려면 다음과 같이합니다:

GET /dogs?color=red&state=running&location=park

요약하자면, 리소스 간의 연결을 단순화하고 매개 변수와 기타 복잡성을 HTTP의 물음표로 숨김으로써 API를 직관적으로 유지하세요.