Lors de la conception et de la mise en place d’une intégration d’API, il arrive fréquemment que l’utilisateur se concentre sur les détails des opérations, des attributs et des paramètres au point de négliger des facteurs qui pourraient avoir un impact significatif sur les performances, la stabilité et la maintenance de son intégration.
Prêter à ces facteurs l’attention qu’ils méritent peut faire la différence entre une intégration peu fiable ou à toute épreuve. Afin que votre intégration soit la meilleure possible, nous vous recommandons vivement d’intégrer ces quatre meilleures pratiques relatives à l’API Smartsheet :
1. Soyez efficace : utilisez des opérations « de masse »
Pour une efficacité maximale, utilisez autant que possible des opérations d’API de masse. En effet, elles vous permettent d’ajouter, de mettre à jour ou de supprimer plusieurs éléments à l’aide d’une seule demande API.
Par exemple, si vous devez mettre à jour 10 lignes dans une feuille, utilisez une seule demande d’actualisation des lignes au lieu d’exécuter 10 demandes distinctes (une pour chaque ligne).
Les opérations de masse améliorent l’efficacité en réduisant considérablement le nombre d’appels sortants nécessaires pour votre intégration. Cela permet de réduire les risques de dépassement de la limite de débit (puisque chaque opération de masse ne compte que pour une seule demande dans le calcul de la limite).
Les opérations d’API suivantes vous permettent actuellement d’effectuer les tâches suivantes en bloc :
Nous ajouterons d’autres opérations « de masse » à l’avenir, alors ne manquez pas ces possibilités supplémentaires d’améliorer l’efficacité. Et n’oubliez pas que, dans la mesure du possible, privilégier les opérations de masse est une meilleure pratique.
Conseil : autorisez la réussite partielle
En général, lorsqu’une erreur est signalée au cours d’une opération de masse, le comportement par défaut consiste à faire échouer l’ensemble de l’opération. Par exemple, si vous faites une demande d’actualisation des lignes et que l’un des objets ligne de la demande n’est pas valide, l’ensemble de l’opération échouera et aucune des lignes ne sera mise à jour.
Toutefois, vous pouvez autoriser la réussite partielle pour les demandes en masse. Cela permet d’exécuter les parties réussies d’une demande même si des erreurs sont signalées pendant l’opération.
2. Soyez pragmatique : respectez les limites de débit
Traitez l’erreur de « dépassement de la limite de débit »
L’API Smartsheet impose actuellement une limite de débit de 300 demandes par minute et par jeton d’accès.
Certaines opérations gourmandes en ressources, telles que l’ajout d’un fichier ou l’obtention de l’historique des cellules, comptent pour 10 demandes dans le calcul de la limite de débit. Si vous la dépassez, les demandes API suivantes (en l’espace d’une minute) renverront un code d’état HTTP 429, ainsi que le corps de réponse JSON suivant :
{
“errorCode”: 4003,
“message”: “Rate limit exceeded.”
}
Nous vous recommandons de concevoir votre intégration de manière à gérer correctement cette erreur de limite de débit. Une façon d’y parvenir consiste à faire en sorte que votre intégration reste en veille pendant 60 secondes lorsque l’erreur est relevée, puis de réitérer la demande.
Vous pouvez également choisir de mettre en œuvre une stratégie de gestion des erreurs, le backoff exponentiel, qui consiste à relancer périodiquement une demande qui a échoué, avec des temps d’attente de plus en plus longs entre les tentatives, jusqu’à ce que la demande réussisse ou que le nombre de tentatives soit atteint.
Évitez d’effectuer des mises à jour « en rafale »
En outre, nous vous recommandons vivement d’éviter d’exécuter des demandes API en rafale pour mettre à jour un objet Smartsheet spécifique à plusieurs reprises dans un laps de temps très court.
Par exemple, si votre intégration ne fait qu’exécuter une demande d’actualisation des lignes une fois par seconde pour la même feuille, cela ne représentera qu’un total de 60 demandes par minute, ce qui respecte parfaitement les limites de débit.
Cependant, la mise à jour d’un même objet aussi rapidement peut entraîner des erreurs d’enregistrement qui ont un impact négatif à la fois sur votre intégration et sur l’expérience utilisateur sur la plateforme Smartsheet.
Afin d’éviter ce cas de figure, concevez votre intégration de manière à ce que les demandes API ne soient jamais exécutées en rafale pour un même objet Smartsheet. Pour une efficacité maximale, envisagez de traiter les modifications par lots et de les soumettre par le biais d’une demande unique grâce à une opération « de masse » (par exemple, l’actualisation des lignes ou l’ajout de colonnes).
Exécutez les demandes de manière séquentielle
Nous vous déconseillons également d’exécuter plusieurs demandes API en parallèle pour mettre à jour un objet Smartsheet spécifique. Cela affectera les performances et entraînera très probablement des erreurs dues à des collisions de sauvegarde.
Afin d’éviter ce cas de figure, concevez votre intégration de manière à ce que les demandes API visant à mettre à jour un objet Smartsheet spécifique soient toujours exécutées de façon séquentielle : exécutez une demande à la fois et ne commencez pas la demande suivante tant que la précédente n’est pas terminée.
3. Soyez judicieux : traitez les erreurs de manière appropriée
Une demande API réussie donnera lieu à un code d’état HTTP 200, ainsi qu’à des données dans le corps de réponse en fonction de l’opération effectuée. Mais que se passe-t-il en cas d’erreur et si vous ne recevez pas de réponse 200 ? La capacité à traiter les erreurs de manière appropriée est un élément essentiel d’une intégration d’API de qualité.
Si une demande API Smartsheet n’aboutit pas, l’API renvoie un code d’état HTTP 4xx ou 5xx, ainsi qu’un corps de réponse JSON précisant les détails de l’erreur survenue. Par exemple, si vous exécutez une demande d’OBTENTION de feuille à l’aide d’un identifiant de feuille non valide (inexistant), la réponse renverra un code d’état HTTP 404 avec le corps de réponse JSON suivant :
{
“errorCode”: 1006,
“message”: “Not Found”
}
Quand devez-vous réessayer ?
Une stratégie de gestion des erreurs réussie exige que votre intégration reconnaisse la différence entre les erreurs susceptibles d’être résolues en réessayant la demande et les erreurs qui ne doivent jamais faire l’objet d’une nouvelle tentative automatique.
Le code d’état HTTP renvoyé avec une réponse vous donne une première indication quant au résultat de la demande.
Recommandations relatives à la gestion des erreurs
Outre le code d’état HTTP, vous devez également évaluer le code d’erreur spécifique à Smartsheet renvoyé dans le corps de réponse pour toute demande ayant échoué. Par exemple :
{
“errorCode”: 1006,
“message”: “Not Found”
}
La documentation de l’API précise les recommandations relatives à la gestion des erreurs pour chaque code d’erreur spécifique à Smartsheet. Nous vous recommandons d’utiliser ces informations pour mettre en œuvre une logique de gestion des erreurs conformément aux indications suivantes :
-
Si le code d’erreur signale une condition d’erreur permanente, ne réitérez pas la demande.
-
Si le code d’erreur signale un problème qui peut être résolu, ne réitérez pas la demande tant que ce n’est pas le cas.
-
Si le code d’erreur signale un problème qui peut être résolu en réitérant la demande après un certain temps, faites cela à l’aide du backoff exponentiel.
4. Soyez rigoureux : procédez à l’enregistrement
Dans l’idéal, votre intégration fonctionnerait de manière fluide dès le premier jour et aucun problème de quelque nature que ce soit ne surviendrait.
Malheureusement, c’est rarement le cas. Lorsque des problèmes surgissent, il est important que votre intégration soit capable d’enregistrer les demandes et les réponses de l’API.
L’accès aux demandes et réponses brutes (y compris les codes et les messages d’erreur détaillés) lorsque des problèmes d’API apparaissent simplifiera le dépannage et écourtera le temps de résolution.
Les exemples suivants montrent le type d’informations que votre application doit enregistrer pour les demandes et les réponses de l’API :
Demande : verbe, URI, en-tête(s), corps de la demande
POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Corps de la demande :
[
{
"title": "FIRST COLUMN - My New Column",
"index": 0,
"type": "TEXT_NUMBER"
},
{
"title": "FIRST COLUMN - My New Column",
"index": 1,
"type": "TEXT_NUMBER"
}
]
Réponse : code d’état HTTP, corps de réponse
État HTTP : 400 Demande incorrecte
Corps de réponse :
{
"errorCode": 1133,
"message": "Column titles are not unique among input columns.",
"detail": {
"columnTitle": "FIRST COLUMN - My New Column"
}
}
Souvent, ces informations vous permettront d’identifier et de résoudre le problème par vous-même. Si ce n’est pas le cas, n’hésitez pas à demander de l’aide à l’adresse devrel@smartsheet.com. Vous devrez nous fournir les informations demande/réponse ci-dessus afin de résoudre le problème.
N’hésitez pas à procéder à l’enregistrement des demandes et des réponses de l’API dès que vous configurez votre intégration pour une expérience optimale.
Commencez à mettre en place votre intégration
Que vous soyez en train de concevoir et de mettre en place une intégration avec Smartsheet, ou que vous ayez déjà réalisé une intégration, le moment est idéal pour intégrer les meilleures pratiques que nous avons abordées dans cet article.
En outre, nous vous encourageons à tirer le meilleur parti du portail des développeurs Smartsheet pour bénéficier des ressources et des conseils présentés dans cet article qui ont tous pour objectif de vous aider à vous familiariser rapidement avec l’API Smartsheet et à déployer votre solution en toute confiance.
Abonnez-vous à la newsletter informatique de Smartsheet pour obtenir des conseils et découvrir des stratégies et des idées visant à aider les professionnels de l’informatique à accroître leur impact sur leur entreprise.