Points d'accès en masse et signalement des échecs partiels

Ce que c'est

Un point d'accès en masse prend plusieurs éléments dans une seule requête : créer 500 contacts, mettre à jour 50 prix, ou, comme dans le traitement par lots JSON de Microsoft Graph (cité), regrouper jusqu'à 20 sous-requêtes arbitraires en un seul appel HTTP. Deux comportements existent. Atomique : tous les éléments sont appliqués, ou aucun. Succès partiel : le serveur applique ce qu'il peut et signale chaque échec. L'AIP-233 de Google (cité) exige qu'une création par lot synchrone soit atomique, et sa justification explique pourquoi : un statut OK laisse entendre que tout a fonctionné, donc ajouter par la suite une information d'échec partiel à une réponse synchrone changerait silencieusement ce que les clients existants présument. Les lots asynchrones, qui renvoient une opération, peuvent prendre en charge le succès partiel et signaler les échecs sous la forme d'une correspondance entre l'index de la requête et un objet de statut ; les erreurs transitoires que le serveur va réessayer ne doivent pas y figurer, et lorsque tous les éléments échouent, l'opération elle-même est marquée comme ayant échoué.

Pourquoi c'est important

Les clients réessaient les requêtes en masse. Avec une sémantique atomique, un nouvel essai est sûr ; avec un succès partiel, un nouvel essai resoumet les éléments déjà appliqués à moins que le client ne puisse distinguer lesquels ont échoué. Le format de signalement détermine si les nouveaux essais créent des doublons.

Comment l'appliquer

• Choisir un comportement par point d'accès, le documenter et ne jamais le changer en place ; passer d'un comportement atomique à un succès partiel nécessite une nouvelle version ou un indicateur explicite dont la valeur par défaut reste l'ancien comportement (l'AIP-233 décrit return_partial_success).
• Signaler le statut au niveau de la requête séparément des résultats par élément. Graph renvoie 200 pour tout lot analysable, donne à chaque sous-réponse son propre status, et précise qu'un 200 sur le lot n'indique pas que les requêtes individuelles ont réussi.
• Repérer les échecs par index, ou par un identifiant fourni par le client qui doit être unique au sein du lot, et réutiliser la forme d'erreur d'un élément unique afin que le code côté client soit partagé.
• Plafonner la taille du lot et indiquer ce plafond. Appliquer l'autorisation, la validation et la limitation de débit à chaque élément ; Graph évalue chaque requête individuellement au regard de la limitation et fait échouer cette requête avec 429.
• Ne prendre en charge un ordre que lorsque c'est nécessaire ; le dependsOn de Graph fait échouer les requêtes dépendantes avec 424 (Failed Dependency) lorsqu'un prérequis échoue.
• Le 207 (Multi-Status) de WebDAV (RFC 4918, cité) existe pour plusieurs statuts par ressource, mais les clients et proxys généralistes ne le connaissent pas ; un corps JSON avec un statut par élément est plus portable.

Pièges

Un point d'accès à succès partiel qui renvoie un simple 200 et enfouit les échecs dans un journal. Reproduire les charges utiles de la requête dans les entrées d'erreur, ce que l'AIP-233 a rejeté pour des raisons de sensibilité des données. Des lots dont le traitement dépasse le délai d'expiration de la passerelle : au-delà d'une certaine taille, le travail en masse relève d'une opération de longue durée.