관련 객체 확장

객체는 관련 객체를 ID로 가리켜요. 카드에는 owner_id와 collection_id가 있어요. 관련 객체 자체가 필요할 때 요청을 한 번 더 보낼 필요는 없어요. expand[]로 요청하면 같은 응답의 expanded 안에 함께 담겨 와요.

curl -G https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "expand[]=owner" \
  --data-urlencode "expand[]=collection"

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "owner_id": 7,
  "collection_id": 3,
  "expanded": {
    "owner": {"id": 7, "username": "anna", "display_name": "Anna Petrova", "role": "editor"},
    "collection": {"id": 3, "name": "support", "title": "Support"}
  }
}

예시는 줄인 것이에요. 확장된 객체에는 그 객체를 읽는 오퍼레이션의 모든 필드가 있어요. ID 필드는 원래 자리에 그대로 있으므로, expand[]를 쓰지 않는 코드는 전과 같은 응답을 받아요.

다음 오퍼레이션에서 관련 객체를 확장할 수 있어요. 점이 있는 경로는 확장된 객체의 관계를 다시 확장해요. 예를 들어 collection.default_owner는 카드가 속한 컬렉션의 기본 담당자예요.

오퍼레이션	경로
`GET /v1/cards/{card_id}`, `GET /v1/cards-by-external-id/{external_id}`	`collection`, `owner`, `verifiers`, `folders`, `collection.default_owner`
`GET /v1/cards`	`data.collection`, `data.owner`, `data.verifiers`, `data.folders`
`GET /v1/jobs/{job_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/jobs`	`data.card`
`GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}`	`event`
`GET /v1/webhooks/{webhook_id}/deliveries`	`data.event`
`GET /v1/push/sources/{source_id}/documents/{external_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/push/sources/{source_id}/syncs/{sync_number}/documents`	`data.card`

각 관계는 관련 객체를 읽는 오퍼레이션의 형태로 담겨요.

관계	`expanded`에 담기는 내용
`collection`	컬렉션. `GET /v1/collections`과 같은 형태예요.
`owner`, `verifiers`, `default_owner`	사용자. `GET /v1/users`와 같은 형태예요. 사용자를 관리할 수 있는 호출자에게는 전체 항목이, 다른 호출자에게는 요약 항목(`brief=true`, 활성 사용자만)이 담겨요. `verifiers`는 `verifier_ids` 순서의 목록이에요.
`folders`	카드가 속한 컬렉션 안에서 호출자가 볼 수 있는 카드의 폴더. `path` 없이 호출한 `GET /v1/folders/{folder_id}`와 같은 형태예요.
`card`	카드. `GET /v1/cards`의 항목과 같은 형태예요.
`event`	이벤트. `GET /v1/webhook-events/{event_id}`와 같은 형태예요.

목록에서

목록에서는 경로를 data.로 시작하세요. 그러면 페이지의 모든 항목에 적용돼요. GET /v1/cards처럼 배열을 반환하는 목록이든, GET /v1/jobs의 jobs나 전송 기록의 items처럼 항목을 필드 안에 담는 목록이든 똑같아요.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "expand[]=data.owner" \
  --data-urlencode "expand[]=data.collection"

Sursa는 관계마다 페이지 전체의 객체를 한 번에 불러오므로, 목록을 확장하는 비용은 항목마다 요청을 하나씩 더 보내는 것이 아니라 요청 하나를 더 보내는 정도예요. 다음 페이지의 커서는 expand[]에 따라 달라지지 않으므로, 다음 페이지에서는 다른 관계를 요청해도 돼요.

규칙

요청당 경로는 최대 10개이고, 각 경로는 점으로 구분한 부분이 최대 2개예요. 예: 목록의 data.owner, 객체의 collection.default_owner.
알 수 없는 경로, 10개를 넘는 경로, 부분이 2개보다 많은 경로는 400 상태와 api.expand_invalid 코드를 반환해요. details.path는 문제가 된 경로를, details.reason은 무엇이 잘못되었는지를 알려 줘요. 값은 unknown_path, too_deep, too_many_paths 중 하나예요.
관련 객체는 호출자가 그 객체를 따로 요청해서 읽을 수 있을 때만 확장돼요. 키에는 그 오퍼레이션의 스코프가 필요해요. 카드, 컬렉션, 폴더는 cards:read, 사용자는 users:read, 이벤트는 webhooks:manage예요. 객체가 호출자에게 보여야 하는 것도 조건이에요. 예를 들어 일부 컬렉션으로 제한된 키라면 그 컬렉션 안의 객체여야 해요. 조건을 채우지 못하면 관계는 null로 확장되고, verifiers에서는 그 사용자 자리에 null이 들어가요. ID는 그대로 반환돼요. folders에는 호출자가 볼 수 있는 폴더만 담겨요.
사용자 지정 소스 키는 카드를 읽지 않으므로, 이 키로는 문서의 card가 항상 null이에요. 카드를 받으려면 import:write와 cards:read 스코프가 있는 API 키로 푸시 API를 호출하세요.
30일보다 오래된 이벤트와 테스트 전송의 이벤트는 null로 확장돼요.
expand[]는 응답에 데이터를 더하기만 해요. 요청이 하는 처리는 바뀌지 않아요.