Aller au contenu
DUST Docs

Conventions de requête : en-têtes de contexte, erreurs, localisation

Tous les points de terminaison /api/v1/* associés à une organisation partagent le même contrat de requête : un jeton porteur, deux en-têtes de contexte qui sélectionnent l’organisation et l’équipe pour lesquelles vous agissez, des corps JSON (les téléversements de fichiers utilisent plutôt le format multipart ou tus), un format d’erreur unique et une pagination par curseur sur les points de terminaison de liste. Cette page définit ce contrat ; les pages propres à chaque domaine le tiennent pour acquis.

En-têtes de contexte

Section intitulée « En-têtes de contexte »

Presque tout dans l’API DUST appartient à une organisation et, au sein de celle-ci, à une équipe. Vous choisissez l’organisation et l’équipe pour lesquelles agit une requête à l’aide de deux en-têtes :

En-têteObligatoireValeur
Dust-Ctx-Org-IdOui, sur les points de terminaison associés à une organisationUUID de l’organisation.
Dust-Ctx-Team-IdNonUUID de l’équipe. Par défaut, l’équipe racine de l’organisation lorsque cet en-tête est omis.
Fenêtre de terminal
curl -fsS "https://apid.dustid.io/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID"

Détails importants en pratique :

  • Les valeurs des en-têtes doivent être des UUID ; une valeur mal formée est rejetée avec 400 INVALID_REQUEST avant l’exécution du point de terminaison.
  • Les variantes préfixées par X- (X-Dust-Ctx-Org-Id, X-Dust-Ctx-Team-Id et l’ancienne paire) sont acceptées comme alias.
  • Les points de terminaison qui exigent un contexte mais ne le reçoivent pas échouent avec les codes d’erreur ORG_ID_REQUIRED ou TEAM_ID_REQUIRED.
  • Quelques points de terminaison sont associés à l’utilisateur et ne nécessitent aucun contexte ; GET /api/v1/me est le plus courant.

Le contexte constitue une frontière d’autorisation

Section intitulée « Le contexte constitue une frontière d’autorisation »

L’autorisation est évaluée pour votre utilisateur agissant au sein de l’équipe désignée par les en-têtes. Le même appel avec un autre Dust-Ctx-Team-Id peut renvoyer des résultats différents : les données que vous pouvez répertorier, lire et modifier correspondent à ce que cette équipe peut voir, c’est-à-dire ses propres fiches ainsi que tout ce qui a été partagé avec elle. L’envoi d’un contexte auquel vous n’appartenez pas n’élève aucun privilège ; les requêtes sont vérifiées par rapport à vos appartenances réelles. Les opérations relatives aux fichiers, aux dossiers, aux relations, aux liens de fiche, à l’importation d’assemblages, aux formulaires de certificat, à Fabric, à la division, aux listes d’équipes connectées, aux pages publiques, aux modèles de page publique, à l’activité et à l’annuaire des utilisateurs exigent une appartenance actuelle à l’équipe sélectionnée et vérifient que celle-ci appartient à l’organisation sélectionnée, tant pour les personnes que pour les comptes de service. L’historique d’une fiche exige en outre l’autorisation de consulter cette fiche ; sélectionner l’ID d’une fiche n’accorde pas l’accès. La création de fiches, y compris en masse, et de modèles exige également une appartenance actuelle à l’équipe sélectionnée. Les listes d’appartenance destinées aux administrateurs de l’organisation restent limitées à l’organisation sélectionnée. Consultez Équipes et partage.

Localisation

Section intitulée « Localisation »

L’en-tête facultatif Dust-Ctx-Locale sélectionne la langue du texte destiné aux utilisateurs et généré par le serveur, notamment les chaînes message des erreurs :

Dust-Ctx-Locale: zh-CN

Les paramètres régionaux pris en charge sont de, es, fr, it, ja, pt, en (par défaut) et zh-CN. Lorsque cet en-tête est absent, le serveur se rabat sur l’en-tête standard Accept-Language, puis sur l’anglais. Les codes d’erreur sont des identifiants stables et ne sont jamais localisés : effectuez vos branchements selon code et affichez message.

Erreurs

Section intitulée « Erreurs »

Les requêtes ayant échoué renvoient un corps JSON au format unique et cohérent :

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to perform this action",
  "status": 401,
  "detail": { }
}
ChampTypeSignification
codestringCode d’erreur stable et lisible par machine. Effectuez vos branchements selon ce champ.
messagestringDescription lisible par un humain, localisée selon Dust-Ctx-Locale.
statusnumberReproduit le code d’état HTTP.
detailobject (facultatif)Contexte supplémentaire relatif à cette erreur, par exemple les détails de validation.

Codes que vous rencontrerez rapidement :

CodeÉtat habituelCas
INVALID_REQUEST400Corps, requête ou en-tête mal formé (détails de validation dans detail).
UNAUTHORIZED401Jeton porteur manquant, expiré ou non valide.
FORBIDDEN403L’utilisateur est authentifié, mais ce contexte d’équipe ne permet pas cette action.
NOT_FOUND / NO_DATA_FOUND404Aucune fiche correspondante n’est visible dans ce contexte.
ORG_ID_REQUIRED / TEAM_ID_REQUIRED400En-tête de contexte manquant sur un point de terminaison à périmètre défini.
THREAD_DATA_CONFLICT409Conflit de concurrence optimiste : votre vue de la fiche n’était plus à jour.

Chaque réponse comporte également un en-tête x-request-id. Consignez-le et incluez-le lorsque vous contactez l’assistance : il permet de retrouver précisément votre requête dans les traces du serveur.

Erreurs et résultats de scan constitue la référence complète : tous les codes que vous êtes susceptible de rencontrer avec leur état, les tableaux canoniques des résultats d’identification et de vérification, des conseils concernant les nouvelles tentatives et la manière de conserver un reçu de scan lorsqu’une opération échoue.

Pagination

Section intitulée « Pagination »

Les points de terminaison de liste (fiches, dossiers, fichiers, événements, modèles, etc.) utilisent une pagination par curseur :

  • Requête : paramètres de requête pageSize (longueur de la page) et cursor (chaîne opaque provenant d’une page précédente). pageSize doit être un entier compris entre 1 et 1 000 ; certains points de terminaison imposent une valeur maximale inférieure. Omettez-le pour utiliser la valeur par défaut du point de terminaison.
  • Les points de terminaison utilisant pageIndex acceptent des entiers compris entre 0 et 1 000 000. Les valeurs de pagination négatives ou fractionnaires sont rejetées.
  • Réponse : le tableau d’éléments accompagné des chaînes de curseur facultatives next et prev. L’absence de next signifie que vous vous trouvez sur la dernière page.
Fenêtre de terminal
# First page
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"


# Follow the cursor
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50&cursor=$NEXT" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"
{
  "threads": [ ... ],
  "next": "eyJjcmVhdGVkQXQiOi...",
  "prev": "eyJjcmVhdGVkQXQiOi..."
}

Les curseurs sont opaques : conservez-les et réutilisez-les sans jamais les analyser. Les points de terminaison de liste qui prennent en charge le tri acceptent order (asc/desc) et un paramètre orderCol propre au point de terminaison (pour les fiches : createdAt, updatedAt, name).

Niveaux d’autorisation

Section intitulée « Niveaux d’autorisation »

Chaque opération exige l’un des trois niveaux de privilège, et le préfixe du chemin vous indique lequel avant même que vous ne consultiez un seul schéma :

PréfixeQui peut l’appelerRemarques
/api/v1/org/*Administrateurs de l’organisation — utilisateurs disposant du rôle admin (ou owner) dans l’organisation désignée par Dust-Ctx-Org-IdCréation d’équipes, mises à jour des équipes, appartenances
/api/v1/connections/*Administrateurs d’équipe — administrateurs de l’équipe agissante désignée par Dust-Ctx-Team-IdCycle de vie des connexions et changements de direction
tout le resteMembres du contexte de la requête, sauf indication contraire de l’opérationFonctionnalités standard

Chaque opération comporte également une extension x-required-role dans la spécification OpenAPI (member, publisher, team-admin ou org-admin) : considérez-la comme la politique de référence propre à l’opération ; une opération sans cette annotation exige member. publisher est une autorisation accordée dans le cadre d’une appartenance à une équipe, et non un niveau distinct : elle est requise pour rendre les données d’une équipe publiquement accessibles en lecture, et les administrateurs d’équipe en disposent toujours. L’appel d’une opération supérieure à votre niveau renvoie 403 FORBIDDEN, quelle que soit la charge utile.

Corps, ID et horodatages

Section intitulée « Corps, ID et horodatages »
  • Les requêtes utilisent Content-Type: application/json, sauf lorsqu’un point de terminaison accepte explicitement des données de formulaire multipart (scans d’identifiants sur /api/v1/tags/*, téléversements de fichiers).
  • Les ID sont des chaînes UUID conformes à la RFC 4122 (threadId, eventId, ID d’organisation et d’équipe, etc.). Considérez-les comme opaques.
  • Les horodatages (createdAt, updatedAt, archivedAt, etc.) sont des chaînes d’horodatage UTC.
  • Les écritures sont consignées sous forme d’événements : la modification d’une fiche ajoute un événement à son historique au lieu de l’écraser silencieusement ; les lectures telles que GET /api/v1/threads/{thread_id} renvoient { thread, events }.

Voir aussi

Section intitulée « Voir aussi »
Signaler un problème dans la documentation