[웹 API 디자인] 7. 페이지네이션 및 부분 응답
페이지네이션 및 부분 응답
부분 응답(Partial response)은 개발자들에게 필요한 정보만 제공할 수 있도록 해줍니다.
예를 들어 트위터 API에서 트윗(tweet)에 대한 요청을 한다고 가정해봅시다. 보통 트위터 앱에서 필요한 정보는 작성자 이름, 트윗의 내용, 타임스탬프(timestamp), 리트윗 수 등이지만, 이외에도 메타데이터 등 많은 정보가 함께 제공됩니다.
이제 구글이 부분 응답 개념을 개척한 것부터 포함하여 몇 가지 주요 API가 응답에서 개발자들에게 필요한 정보만 제공하는 방식에 대해 알아봅시다.
/people:(id,first-name,last-name,industry)
이 요청은 ID, 이름, 성, 그리고 업종을 반환합니다.
LinkedIn은 이렇게 간결한 :(…) 구문을 사용하여 부분 선택(partial selection)을 수행하지만 이는 명시적이지 않습니다. 또한 검색 엔진을 사용하여 의미를 역설하는 것이 어렵습니다.
/joe.smith/friends?fields=id,name,picture
?fields=title,media:group(media:thumbnail)
Google과 Facebook은 유사한 접근 방식을 취하며 잘 작동합니다.
각각 필드를 나열할 수 있는 선택적 매개 변수인 fields를 가지고 있습니다.
이 예시에서 보는 것처럼 추가 리소스에서 다른 정보를 가져 오기 위해 응답에 하위 객체를 넣을 수도 있습니다.
쉼표로 구분된 선택적 필드 추가
Google의 접근 방식은 매우 효과적입니다.
다음은 이 접근 방식을 사용하여 필요한 정보만 가져오는 방법입니다. 예를 들어, 개(dog) API를 사용하여 다음 정보를 가져올 수 있습니다.
/dogs?fields=name,color,location
이 방법은 읽기 쉽고, 개발자가 필요한 정보만 선택할 수 있으며, 모바일 앱에서 중요한 대역폭 문제를 줄일 수 있습니다.
부분 선택 구문은 관련 리소스를 포함하여 필요한 정보를 얻기 위해 필요한 요청 수를 줄이는 데에도 사용될 수 있습니다.
개발자들이 데이터베이스에서 객체를 페이지별로 처리하기 쉽도록 만들어라
거의 항상 데이터베이스에서 모든 자원을 반환하는 것은 좋지 않은 생각입니다.
Facebook, Twitter 및 LinkedIn이 페이지네이션을 처리하는 방법을 살펴보겠습니다.
Facebook은 offset과 limit을 사용합니다.
Twitter는 page와 rpp(페이지당 레코드 수)를 사용합니다.
LinkedIn은 start와 count를 사용합니다.
의미론적으로 Facebook과 LinkedIn은 같은 일을 합니다. 즉, LinkedIn의 start 및 count는 Facebook의 offset 및 limit과 동일한 방식으로 사용됩니다.
각 시스템에서 50에서 75개의 레코드를 가져 오려면 다음과 같이 사용하면 됩니다. • Facebook - offset 50 및 limit 25 • Twitter - page 3 및 rpp 25 (페이지당 레코드 수) • LinkedIn - start 50 및 count 25
limit과 offset 사용하기
우리는 limit과 offset을 추천합니다. 이것은 보편적으로 사용되며, 주요 데이터베이스에서 잘 이해되며, 개발자들이 쉽게 사용할 수 있습니다.
/dogs?limit=25&offset=50
메타데이터
우리는 또한 각 페이지화된 응답에 메타데이터를 포함하는 것을 제안합니다. 이 메타데이터는 개발자에게 사용 가능한 총 레코드 수를 나타내는 것입니다.
그렇다면 기본 값은 어떻게 설정해야 할까요?
제 생각에는 limit=10, offset=0이 기본값으로 적당합니다.
(limit=10&offset=0)
하지만 이는 데이터 크기에 따라 다를 수 있습니다. 자원의 크기가 큰 경우 10보다 적은 값으로 제한하는 것이 좋고, 자원의 크기가 작은 경우 더 큰 값으로 설정하는 것이 적절할 수 있습니다.
요약하면,
선택적인 필드를 쉽게 지정할 수 있도록 쉼표로 구분된 목록으로 선택 가능한 필드를 추가하여 부분 응답(partial response)을 지원합니다.
limit과 offset을 사용하여 개발자가 쉽게 객체를 페이지네이션 할 수 있도록합니다.
댓글남기기