API 목록 페이지네이션

API 목록 페이지네이션 (API list pagination)

Boundary는 API 페이지네이션 기능을 사용해서 시스템 리소스를 압도하지 않으면서 큰 결과 목록을 검색하고 필터링할 수 있게 해줘요.

출처: HashiCorp Boundary docs

본문

소개 (Introduction)

리소스에 대해 list 작업을 수행하면 API 요청은 기본적으로 처음 1000개 결과를 반환해요. Boundary가 제공한 토큰을 포함한 파라미터를 추가해서 list 명령을 반복하면 다음 페이지의 결과를 요청할 수 있어요.

초기 페이지네이션 (Initial pagination)

리소스에 대해 list 작업을 실행하면 초기 결과가 생성 시간과 공개 ID의 내림차순(가장 최근 생성이 먼저)으로 정렬돼요. Boundary는 최대 응답 수를 최상위 필드 response_type과 list_token과 함께 반환해요. response_type이 delta이면 목록에 더 많은 항목이 있다는 뜻이에요.

list 토큰에는 진행 중인 페이지네이션과 관련된 일반 메타데이터가 들어 있어요. 다음 페이지의 결과를 요청하려면 list 작업을 다시 실행하고 마지막 응답에서 Boundary가 제공한 list_token을 포함하면 돼요. Boundary는 새로운 response_type과 list_token 값과 함께 다음 페이지 결과를 반환해요.

response_type이 complete로 읽힐 때까지 list_token 값을 사용해서 새 결과 페이지를 계속 볼 수 있어요. 유효하지 않은 토큰을 구성하면 유효하지 않은 토큰 오류를 받게 돼요.

업데이트/삭제된 리소스 요청 (Request updated and deleted resources)

response_type이 complete로 읽히면 초기 list 작업을 실행했을 때 사용 가능했던 모든 결과를 본 거예요. 이제 페이지네이션을 시작한 이후로 업데이트되거나 삭제된 리소스를 요청할 수 있어요.

캐시된 목록 결과를 새로고침하려면 이전 응답의 list_token으로 또 다른 list 요청을 만들어요. Boundary는 초기 작업을 실행할 때와 마찬가지로 응답의 일부로 response_type과 list_token을 반환해요. response_type이 delta이면 목록에 더 많은 항목이 있다는 뜻이에요. response_type이 complete로 읽힐 때까지 list_token을 파라미터로 사용해서 새 결과 페이지를 계속 볼 수 있어요.

Boundary는 또한 새로고침 작업의 일부로 최상위 removed_ids 응답을 포함해요. removed_ids 응답에는 이전 list 작업의 결과를 페이지네이션하기 시작한 이후 삭제된 모든 리소스의 ID가 들어 있어요. 삭제된 모든 리소스는 결과의 첫 페이지에 포함돼요.

30일이 지나면 list_token이 만료되므로, 토큰 없이 새 list 요청을 만들어 전체 결과 목록을 다시 생성해야 해요. create_time이 30일보다 오래된 토큰으로 list 요청을 하면 Boundary는 그 토큰을 유효하지 않은 토큰으로 취급하고 오류를 반환해요.

응답 구조 (Response structure)

모든 list 엔드포인트는 다음 파라미터를 지원해요.

list_token (선택) — 이전 list 응답에서 반환된 불투명한 토큰이에요. 값을 제공하지 않으면 페이지네이션이 처음부터 시작돼요.
page_size (선택) — 검색 결과 페이지에 포함할 항목 수를 나타내는 부호 없는 정수예요. 값을 포함하지 않거나 0을 포함하면 Boundary가 기본 페이지 크기 1000개 항목을 사용해요. 설정하면 page_size 값이 기본 페이지 크기를 덮어써요. 컨트롤러 관리자는 사용자가 요청할 수 있는 최대 페이지 크기를 제한하는 max_page_size 옵션도 설정할 수 있어요.

Boundary는 다음 응답 파라미터를 반환해요.

response_type — 응답이 delta 목록인지 complete 목록인지 정의해요. 마지막 페이지가 반환될 때까지 값은 delta이고, 그 시점에 complete가 돼요.
list_token — 초기 이후의 후속 목록 요청에 포함되는 불투명한 토큰으로, 클라이언트가 결과를 계속 페이지네이션할 수 있게 해줘요.
sort_by — 반환된 항목이 정렬되는 열 이름이에요. 이 속성은 응답에 포함되어 각 엔드포인트의 정렬 순서가 명시적이도록 해요.
sort_dir — 반환된 항목이 정렬되는 방향이에요. 응답에는 내림차순의 desc 또는 오름차순의 asc가 포함될 수 있어요.
items — 항목 목록이에요.
est_item_count — 결과 목록에서 사용 가능한 총 항목 수를 나타내는 부호 없는 정수예요. 페이지네이션 도중 항목 수가 바뀔 수 있으므로 이 숫자는 추정치일 수 있어요.

예시 응답 (Example response)

{
  "response_type": "<delta|complete>",
  "list_token": "<opaque-token>",
  "sort_by": "created_time",
  "sort_dir": "desc",
  "est_item_count": 1000,
  "items": [
    {
      "id": "ttcp_1234567890",
      "scope_id": "p_1234567890"
    },
    {
      "id": "ttcp_2234567890",
      "scope_id": "p_1234567890"
    }
  ]
}

제약과 한계 (Constraints and limitations)

업데이트가 너무 빈번해서 새로고침 작업이 실행되는 동안 결과가 바뀔 수 있는 시나리오에서는, 그 업데이트가 새로고침된 목록에 전혀 나타나지 않을 수 있어요. 리소스를 자주 업데이트하거나 list 작업을 실행하는 동안 데이터를 업데이트한다면, 새로고침을 수행하는 대신 전체 결과 목록을 생성하는 것을 HashiCorp가 권장해요.

워커는 새로고침 작업에 포함되지 않아요. 워커가 컨트롤러로 보내는 업데이트가 너무 빈번해서 새로고침으로 포착할 수 없기 때문이에요. 워커 리소스 목록을 업데이트하려면 전체 결과 목록을 다시 생성해야 해요.

결과 목록을 새로고침하면 목록에 중복 항목이 보일 수 있어요. 이는 여러 데이터베이스 트랜잭션에 걸쳐 검색할 때의 근본적인 트레이드오프예요.

API 목록 페이지네이션