6 erreurs d'API fréquentes et comment les empêcher de se produire

Les API sont une partie de plus en plus importante de l'économie du 21e siècle et de notre vie quotidienne. D'énormes entreprises comme Stripe et Amazon ont été construites sur d'excellentes plateformes de développement. Même les outils « analogiques » comme les systèmes téléphoniques de bureau sont de plus en plus exposés aux API. Des produits VoIP de plus en plus avancés intègrent systèmes téléphoniques pour les petites entreprises avec des logiciels comme Google Workspace. Cela ouvre de nouvelles expériences puissantes pour les employés et les clients. Mais les API ne sont pas au-dessus des erreurs. Que vous soyez un développeur de projet amateur ou un millionnaire Produit basé sur SaaS utilisateur, vous constaterez que les problèmes sont inévitables.

Qu'est-ce qu'une erreur/un échec d'API ?

An Erreur API se produit lorsqu'un serveur ne parvient pas à localiser la ressource demandée auprès du fournisseur d'API. Dans de tels cas, un message d'erreur numérique est renvoyé pour aider à identifier l'erreur spécifique. Les causes courantes d'erreurs d'API incluent des problèmes au niveau du point de terminaison, des paramètres incorrects ou des problèmes avec la clé API lors de l'appel de requête. La résolution de ces erreurs est cruciale pour une communication transparente entre les applications et pour garantir une récupération réussie des données auprès du fournisseur d'API.

6 erreurs API courantes

Certaines erreurs API courantes sont :

• Erreurs HTTP/HTTPS.
• Erreurs API inutiles.
• Mélanges de méthodes.
• En-têtes Content-Type/Accept manquants.
• Erreurs d'autorisation.
• Erreurs de formatage des données.

1. Erreurs HTTP/HTTPS

L'une des erreurs d'API les plus courantes se produit lorsqu'il y a confusion entre les protocoles http:// et https:// dans les URL.

Pour les développeurs, le problème est que certaines API ne prennent en charge que le protocole HTTP alors que d'autres sont compatibles HTTPS. Certains prennent en charge différentes normes à différents points de terminaison dans le même produit centré sur le client.

Cela peut devenir encore plus déroutant lorsque les développeurs enchaînent plusieurs API ensemble. S'il s'agit de développeurs internes qui créent des solutions « DIY » pour les communications professionnelles asynchrones avec des équipes distantes. Les développeurs doivent passer du temps à localiser le point de terminaison à l'origine du problème, puis créer une solution de contournement pour que les deux API restantes se parlent.

Si vous êtes un Fournisseur d'API, vous pouvez éviter cette erreur en mettant en place des stratégies HTTPS spécifiques. Par exemple, vous pouvez faire en sorte que votre API redirige automatiquement les requêtes HTTP vers les requêtes HTTPS au fur et à mesure qu'elles arrivent.

2. Messages d'erreur d'API inutiles

Pour vos utilisateurs, la qualité de vos messages d'erreur peut faire la différence entre un bref hoquet et une heure passée à s'arracher les cheveux, ce qui aide à réduire le taux de désabonnement des clients.

HTTP fournit plus de 70 codes d'état http, mais au minimum, vous n'avez qu'à implémenter les codes les plus courants avec lesquels les développeurs ont l'habitude de travailler. Voici quelques exemples :

200 OK

Tout bon! Veillez simplement à ne fournir ce code d'état que si tout est réellement is D'ACCORD. L'API Graph de Facebook est connue pour fournir un code 200 chaque fois qu'elle renvoie avec succès une sortie, même si cette sortie contient un code d'erreur.

400 Bad Request

Cela est presque toujours dû à une faute de frappe dans la saisie de votre utilisateur. Mais cela ne signifie pas que vous êtes tiré d'affaire ! Assurez-vous que votre message d'erreur fournit des détails sur l'entrée défectueuse afin que l'utilisateur puisse le réparer rapidement.

401 non autorisé

Cet état signifie que la saisie est correcte mais qu'il manque un code d'autorisation à la demande des utilisateurs. A ne pas confondre avec…

403 Interdite

Cela signifie que le code d'autorisation est reconnu comme valide mais que l'utilisateur n'a pas la permission. Par exemple, un utilisateur peut essayer d'accéder à quelque chose qui n'est disponible que pour les administrateurs, un problème de sécurité croissant avec le personnel distant.

404 Introuvable

La demande de l'utilisateur est valide, mais le point de terminaison ou la ressource qu'il demande n'existe pas. Cela peut être dû au fait que le fichier a été supprimé depuis, mais assurez-vous que cela n'est pas dû à une erreur HTTP/HTTPS.

429 Trop de demandes

Cela se produit lorsque le même utilisateur essaie d'appeler l'API un trop grand nombre de fois en succession rapide. Après un certain nombre d'attaques DDoS très médiatisées au cours de la dernière décennie, les services Web surveillent de près qui accède à leur serveur et à quelle fréquence.

Cette limitation de débit est similaire à ce que vous trouverez sur n'importe quel domaine ou sur d'autres gros sites. Les fournisseurs d'hébergement Web comme Cloudflare gèrent la protection DDoS pour les domaines hébergés sur leurs serveurs. Pour les API, ces protections doivent être intégrées.

Erreurs d'API 5xx

Les codes d'état commençant par 5 sont tous des erreurs de serveur, potentiellement de votre côté. Si tel est le cas, assurez-vous que vos messages d'erreur aident ou rassurent l'utilisateur. Il peut s'agir d'informations de contact ou d'une page contenant des informations en direct sur la disponibilité/les temps d'arrêt.

Les fournisseurs d'API peuvent éviter les mauvais messages d'erreur avec juste un peu d'adaptation et de gestion des erreurs. Allez au-delà du code d'erreur et utilisez des messages clairs et succincts qui renvoient à la documentation.

Les fournisseurs de logiciels doivent avoir créé un profil de consommateur cible des développeurs qui utiliseront leur API. Les messages d'erreur peuvent et doivent être adaptés aux types de tâches numériques qu'ils essaieront d'accomplir.

Jetez un œil à ce message d'erreur de Twilio, dont l'API permet aux développeurs de passer un appel VoIP.

“`

{

« indicatif » : 21211,

"message": "Le numéro 'À' 5551234567 n'est pas un numéro de téléphone valide.",

"plus_info": "https://www.twilio.com/docs/errors/21211",

"statut": 400

}

“`

Au-delà du statut standard 400, il y a un code d'erreur personnalisé "21211" en haut. Le message fait même référence au numéro de téléphone virtuel spécifique à l'origine du problème. Il renvoie l'utilisateur à la page de sa documentation où il discute du problème 21211.

Les mauvais messages d'erreur peuvent être une énorme pierre d'achoppement pour les développeurs qui tentent d'intégrer une API dans leur entreprise axée sur les produits. Un processus d'intégration simple est essentiel au succès d'une API. L'une des premières choses que beaucoup de gens entendent à propos de Stripe est la facilité avec laquelle il suffit de coller quelques lignes de code et de faire avancer les paiements. De bons messages d'erreur ne sont donc pas seulement importants pour la fonctionnalité, ils constituent également un excellent atout marketing pour votre API.

3. Mélanges de méthodes

Les API et leurs utilisateurs peuvent rencontrer des erreurs lorsqu'ils mélangent leurs méthodes de requête. Si l'utilisateur envoie une requête POST qui est redirigée et renvoyée en tant que requête GET, cela peut provoquer une erreur frustrante qui n'est pas de sa faute.

Une documentation peu claire est une autre cause d'erreurs de méthode. Cela peut se produire lorsqu'une section de votre documentation n'explique pas quelles méthodes sont requises ou utilise entièrement le mauvais verbe. (Attention à ne pas utiliser le mot "get" et GET de manière interchangeable. Assurez-vous que la mise en forme de vos documents est claire et enregistrez-vous un e-mail de support client.)

Développez une API REST robuste et sécurisée en quelques minutes

Voir la démo

4. En-têtes Content-Type/Accept manquants

La plupart des appels d'API ont au moins deux éléments de données d'en-tête : Content-Type et Accept. Ces en-têtes aident deux parties, telles que deux API, à négocier le type de données envoyé et les types qui seront acceptés en retour. Comme toute négociation, celles-ci peuvent échouer.

Certaines API accepteront les demandes qui n'ont pas ces en-têtes s'il n'y a aucune raison d'être aussi strict. Chaque ligne de code introduit des erreurs possibles dans le logiciel, de sorte que les fournisseurs de PBX cloud ne spécifient souvent pas d'exigence d'en-tête s'ils n'y sont pas obligés. Mais dans les API commerciales avec des problèmes de sécurité, les développeurs demanderont des en-têtes Content-Type et Accept spécifiques. Cela leur permet de contrôler étroitement ce qui est autorisé dans leur système et ce qui est autorisé à y circuler.

Content-Type indique à l'API le format de la date que vous envoyez, et Accept indique à l'API ce qu'il faut renvoyer. Les API peuvent nécessiter uniquement que vous ayez quelque chose dans les en-têtes, certains accepteront des types spécifiques et en rejetteront d'autres.

Ces informations doivent être spécifiées dans la documentation lorsqu'il n'y a pas de risque pour la sécurité, mais certains outils de développement peuvent perturber les utilisateurs. Considérez curl, qui inclut automatiquement l'en-tête Accept par défaut dans les requêtes. Les fournisseurs d'API peuvent anticiper ces bizarreries d'outils, en modifiant la demande ou en envoyant un message d'erreur spécifique.

5. Erreurs d'autorisation

Il s'agit d'une erreur API courante et souvent très simple. Les API utilisant le protocole de sécurité OAuth 2 nécessitent une donnée d'en-tête supplémentaire pour traiter les requêtes. Il s'agit de l'en-tête "authorization", contenant la clé privée nécessaire à l'API pour traiter la requête.

C'est une erreur courante d'envoyer un en-tête « authentification » à la place. En effet, les développeurs et la documentation parlent souvent d'authentification et d'autorisation de manière interchangeable. Mais même si l'en-tête est correctement étiqueté comme "autorisation", des erreurs de formatage déroutantes peuvent perturber les gens.

Assurez-vous que les demandes d'API OAuth 2 sont formatées comme suit, avec le drapeau "Bearer" avant la clé privée :

“`

Autorisation : Porteur {your_api_key_here}

“`

Les paires nom d'utilisateur et mot de passe doivent être formatées comme "nom d'utilisateur: mot de passe". Mais même si la demande d'API ne nécessite pas de mot de passe, les utilisateurs devront peut-être ajouter deux points à la fin. Les fournisseurs d'API peuvent ajouter eux-mêmes les deux-points ou indiquer clairement dans la documentation quel est exactement le formatage.

6. Erreurs de formatage des données

Même si l'utilisateur fait tout correctement, Apis peut toujours cracher des données dans le mauvais format. Si l'API donne aux utilisateurs leurs données en HTML plutôt que dans le JSON qu'ils pensaient avoir demandé, cela pourrait provoquer un plantage total. Pire encore, leur développement logiciel pourrait volontiers accepter les données et les traiter d'une manière inattendue.

Si le développeur essaie de joindre des services pour mesurer le taux de conversion des sites de commerce électronique, l'équipe marketing ne verra pas le code. Ils pourraient passer des jours à examiner des données erronées avant que quiconque ne se rende compte que quelque chose ne va pas.

Nous avons mentionné les méthodes de requête par défaut sur GET en raison d'une redirection. Mais le plus souvent, cette erreur se produit lorsque l'utilisateur n'a pas spécifié correctement l'en-tête Accept, voire pas du tout. Cela pourrait donner aux fournisseurs une raison d'être plus stricts sur les types de contenu qu'ils acceptent, même s'il ne s'agit pas d'un risque de sécurité.

Les fournisseurs d'API doivent également vérifier les types de réponses qu'ils peuvent recevoir par défaut ou par erreur. Si votre API n'a aucune raison de traiter du HTML, vous devez rejeter ce type de contenu. Cela évite les problèmes que vous pourriez rencontrer avec des outils courants. Par exemple, chaque fois que Nginx obtient un délai d'expiration de la demande, cela peut vous donner une erreur HTML que votre API n'a aucune idée de la façon de traiter.

La prévention des erreurs expliquée

La prévention d'un grand nombre de ces erreurs courantes se résume à des tests approfondis. C'est également une bonne idée de contrôler étroitement les données que votre API acceptera une fois qu'elles seront disponibles dans la nature. De plus, les fournisseurs d'API devraient accorder une grande importance à l'excellente documentation de l'API et aux messages d'erreur.

Cela aidera les utilisateurs à résoudre les problèmes par eux-mêmes, mais s'il s'agit d'un logiciel pour le service client, cela vous aidera à résoudre le problème plus rapidement. Une fois que vous avez identifié ce défaut, il est temps de voir si vous pouvez améliorer vos documents ou même résumer tout le problème afin que cela ne se reproduise plus.

En savoir plus sur la gestion simple et rapide des API de bout en bout

Télécharger Whitepaper