Pagination

Les listes d’un espace de travail, comme ses factures ou ses transactions bancaires, renvoient une page à la fois. Une page contient jusqu’à limit éléments : 20 par défaut, 100 au plus.

Lire toutes les pages

Une liste répond avec ses éléments dans data, la limit de la requête, et un nextCursor quand la page est pleine. Renvoyez ce curseur comme startAfter pour obtenir la page suivante, et arrêtez-vous à une page sans nextCursor :

async function listAllInvoices(workspaceId) {
const url = new URL(process.env.SWAY_API + '/workspaces/' + workspaceId + '/invoices');
const headers = {Authorization: 'Bearer ' + process.env.SWAY_API_KEY};
url.searchParams.set('limit', '100');
const invoices = [];
while (true) {
  const response = await fetch(url, {headers});
  if (!response.ok) throw new Error('Sway API answered ' + response.status);
  const page = await response.json();
  invoices.push(...page.data);
  if (!page.nextCursor) return invoices;
  url.searchParams.set('startAfter', page.nextCursor);
}
}

import os
import requests

def list_all_invoices(workspace_id):
url = os.environ["SWAY_API"] + "/workspaces/" + workspace_id + "/invoices"
headers = {"Authorization": "Bearer " + os.environ["SWAY_API_KEY"]}
params = {"limit": 100}
invoices = []
while True:
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
page = response.json()
invoices.extend(page["data"])
if "nextCursor" not in page:
return invoices
params["startAfter"] = page["nextCursor"]

• Une dernière page pleine porte encore un nextCursor, et la page vers laquelle il pointe est vide : la boucle s’arrête une requête plus tard.
• Le curseur est opaque : renvoyez-le tel quel. Il contient la valeur de tri et l’ID du dernier élément, si bien que des éléments de même valeur reviennent dans un ordre stable.
• Un curseur mal formé reçoit 400 invalid-argument. Une limit absente ou invalide revient à 20, et une valeur plus grande à 100.

Obtenir des éléments par leur ID

?ids= prend jusqu’à 30 ID séparés par des virgules et renvoie ces éléments en un appel, comme ?ids=Hk2xNq8vR4tYw6ZbPj3c,Rm5tB8wQ2zLx7nVc4pKs. Il ignore limit, startAfter et les filtres.

Ne garder que certains champs

?fields= ne garde que les propriétés qu’il nomme dans la réponse, ou dans chaque élément d’une liste ; un point atteint une propriété imbriquée. ?fields=firestoreId,invoiceStatus,totalAmount.amount renvoie trois propriétés de chaque facture. Chaque endpoint l’accepte.

Résultats de recherche

Les cinq endpoints de recherche paginent par numéro : transactions bancaires, tiers, factures, paiements en brouillon et fichiers de l’espace de travail.

• page compte à partir de 0, et size prend de 1 à 100 éléments, 20 par défaut.
• La réponse ne contient que data, sans curseur ni total : demandez la page suivante jusqu’à ce qu’une page revienne avec moins de size éléments.

Espaces de travail

GET /workspaces renvoie chaque espace de travail de l’utilisateur de la clé en une réponse, sans page ni limit.