Développer les objets liés

Les objets désignent les objets liés par leur identifiant : une fiche a owner_id et collection_id. Quand vous avez besoin de l’objet lié lui-même, inutile d’envoyer une seconde requête. Demandez-le avec expand[] : il arrive dans la même réponse, à l’intérieur de 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"}
  }
}

L’exemple est abrégé : un objet développé a tous les champs de sa propre opération de lecture. Les champs d’identifiant restent à leur place : le code qui n’utilise pas expand[] reçoit la même réponse qu’avant.

Les opérations suivantes développent les objets liés. Un chemin avec un point développe un lien de l’objet développé : par exemple, collection.default_owner est le responsable par défaut de la collection de la fiche.

Opération	Chemins
`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`

Chaque lien arrive sous la forme que lui donne l’opération qui lit l’objet lié :

Lien	Ce qui arrive dans `expanded`
`collection`	La collection, comme dans `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	L’utilisateur, comme dans `GET /v1/users` : l’entrée complète pour un appelant autorisé à gérer les utilisateurs, l’entrée abrégée (`brief=true`, utilisateurs actifs uniquement) pour les autres appelants. `verifiers` est une liste dans l’ordre de `verifier_ids`.
`folders`	Les dossiers de la fiche dans sa collection que l’appelant peut voir, comme dans `GET /v1/folders/{folder_id}` sans `path`.
`card`	La fiche, comme un élément de `GET /v1/cards`.
`event`	L’événement, comme dans `GET /v1/webhook-events/{event_id}`.

Dans les listes

Pour une liste, commencez le chemin par data. : il s’applique alors à chaque élément de la page. C’est la même chose pour une liste qui renvoie un tableau, comme GET /v1/cards, et pour une liste qui range ses éléments dans un champ, comme jobs de GET /v1/jobs ou items du journal des livraisons.

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 charge en une fois chaque lien pour toute la page : développer une liste coûte donc à peu près autant qu’une requête supplémentaire, et non une requête par élément. Le curseur de la page suivante ne dépend pas de expand[] : vous pouvez donc demander d’autres liens pour la page suivante.

Règles

Jusqu’à 10 chemins par requête, chacun d’au plus 2 segments de profondeur : data.owner dans une liste, collection.default_owner sur un objet.
Un chemin inconnu, plus de 10 chemins ou un chemin de plus de 2 segments renvoie 400 avec le code api.expand_invalid. details.path nomme le chemin, et details.reason indique ce qui ne va pas : unknown_path, too_deep ou too_many_paths.
Un objet lié n’est développé que pour un appelant qui pourrait le lire avec sa propre requête. La clé a besoin de la portée de cette opération : cards:read pour les fiches, les collections et les dossiers, users:read pour les utilisateurs, webhooks:manage pour les événements. L’objet doit aussi être visible de l’appelant, par exemple à l’intérieur des collections d’une clé limitée à certaines collections. Sinon, le lien est développé en null, et dans verifiers l’utilisateur est remplacé par null. Son identifiant est tout de même renvoyé. folders ne liste que les dossiers que l’appelant peut voir.
Une clé de source personnalisée ne lit pas les fiches : avec elle, card d’un document vaut donc toujours null. Pour obtenir la fiche, appelez l’API d’envoi (push) avec une clé API qui a les portées import:write et cards:read.
Un événement de plus de 30 jours et l’événement d’une livraison de test sont développés en null.
expand[] ne fait qu’ajouter des données à la réponse. Il ne change jamais ce que fait la requête.