Article original : How to Design and Develop Web APIs: Essential Guidelines for Developers

Les applications logicielles ont facilité et amélioré notre vie de nombreuses manières. Nous les utilisons presque quotidiennement, et certaines personnes se retrouvent à utiliser des applications plus fréquemment qu'elles n'interagissent avec d'autres personnes.

Mais comment les applications interagissent-elles entre elles ? Eh bien, elles le font via des API - Interfaces de Programmation d'Applications. Dans cet article, vous apprendrez ce que sont les API. Nous nous concentrerons spécifiquement sur les API Web et leur conception et développement.

Qu'est-ce qu'une API Web ?

Les API Web sont un type d'API conçu pour être utilisé sur le web. En d'autres termes, les applications logicielles, systèmes et services basés sur le web utilisent les API Web pour échanger des informations sur Internet. Elles envoient des requêtes et reçoivent des réponses, généralement dans des formats tels que JSON ou XML.

Les API Web jouent un rôle crucial dans le développement logiciel moderne pour les raisons suivantes :

  1. Interopérabilité : Les API sont agnostiques en termes de technologie, ce qui signifie qu'elles permettent à différents systèmes logiciels de communiquer entre eux, indépendamment de la stack technologique. Cela permet aux développeurs d'intégrer diverses applications de manière transparente.

  2. Évolutivité : Les API Web soutiennent le développement modulaire, permettant aux différents composants d'une application d'être construits, débogués et mis à l'échelle indépendamment. Cela améliore grandement l'évolutivité du système.

  3. Flexibilité et Extensibilité : En suivant des pratiques standard et des règles bien définies, les API Web aident les applications à étendre leurs fonctionnalités. Elles sont également suffisamment flexibles pour permettre aux développeurs de créer des applications dynamiques.

Approches pour développer des API Web

Les API Web peuvent être développées en utilisant diverses méthodes en fonction des exigences. Voici quelques approches couramment suivies :

  • REST - Representational State Transfer (REST) utilise le protocole HTTP pour effectuer des opérations. Elles fonctionnent de manière sans état, ce qui signifie que chaque requête doit inclure toutes les informations nécessaires pour que le récepteur puisse les traiter et répondre.

  • SOAP - Simple Object Access Protocol utilise XML pour échanger des informations de manière structurée.

  • GraphQL - utilisé pour interroger et manipuler des API.

  • gRPC - un framework d'appel de procédure à distance qui utilise HTTP/2 pour transporter des informations.

Dans les sections à venir, nous explorerons la conception et le développement des API, en nous concentrant sur les API REST comme protocole central de notre discussion.

Comprendre les exigences et objectifs

Dans tout processus de développement logiciel, il est crucial de comprendre les exigences et le cas d'utilisation prévu avant de commencer. Cela vous aide à planifier et à estimer le coût, le temps et les autres ressources dont vous aurez besoin pour le projet.

Il en va de même lors de la création d'API RESTful. Vous devez déterminer si les applications échangeront des informations de manière sans état, si les entités impliquées peuvent être représentées comme des ressources, et si les services sont suffisamment flexibles pour travailler avec différents formats de données.

Définir les ressources et les endpoints

Les API REST tournent autour des ressources, qui sont des entités représentant les données ou les objets dans le système. Chaque ressource est identifiée par un URI unique appelé identifiant de ressource. Ces ressources peuvent être accessibles et manipulées via des endpoints, qui sont des URL spécifiques recevant et traitant les requêtes du client.

Les bonnes pratiques suggèrent d'utiliser des noms pour les ressources dans les endpoints plutôt que des verbes qui pourraient indiquer une opération sur la ressource.

Considérez l'exemple suivant : https://api.example.com/products

L'endpoint suit la bonne pratique d'utiliser un nom pour la ressource (dans ce cas, products). Remarquez comment j'ai utilisé la forme plurielle - products ? Il est également conseillé d'utiliser des pluriels si vous travaillez avec une collection d'objets.

Cependant, l'endpoint suivant https://api.example.com/add-product n'est pas recommandé car il utilise un verbe et essaie de décrire une action sur la ressource. Cette approche peut devenir compliquée pour des opérations plus complexes.

Un autre aspect important de la convention de nommage standard des endpoints est l'utilisation d'une structure hiérarchique. Cela aide à représenter clairement la relation entre les ressources.

Par exemple : https://api.example.com/categories/{categoryId}/products/{productId}. Ici, nous définissons un endpoint qui maintient une hiérarchie claire entre les ressources category et product.

Utilisation des méthodes HTTP et des codes de statut

Dans les API REST, HTTP est utilisé pour la communication entre le client et le serveur. HTTP dispose de méthodes standard principalement utilisées pour effectuer des opérations sur les ressources. Voici une liste de ces méthodes ainsi que leurs objectifs :

  • GET - Récupérer les détails de la ressource. Ces détails sont retournés par le serveur dans le corps du message de réponse.

  • POST - Créer une nouvelle ressource. Les détails de la ressource à créer sont envoyés dans le corps du message de requête.

  • PUT - Créer ou mettre à jour une ressource, selon sa disponibilité. Les détails de la ressource à créer ou mettre à jour sont envoyés dans le corps du message de requête.

  • DELETE - Supprimer une ressource.

  • PATCH - Mettre à jour partiellement une ressource. Les modifications à apporter à la ressource sont envoyées dans le corps du message de requête.

L'approche recommandée pour développer une API REST bien définie est d'utiliser correctement ces méthodes HTTP pour effectuer les opérations CRUD (Create, Read, Update, Delete) correspondantes sur la ressource. De plus, vous devez vous assurer que l'API répond au client avec un code de statut HTTP approprié dans le corps du message de réponse.

Les codes de statut reflètent le résultat final d'une requête. Voici quelques-uns des codes de statut HTTP courants que vous pouvez utiliser :

  • 200 OK

  • 201 Created

  • 204 No Content

  • 400 Bad Request

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

  • 504 Gateway Timeout

Utilisez un code de statut HTTP approprié qui représente avec précision le résultat de la requête que votre endpoint d'API traite. Vous pouvez également implémenter un code de statut HTTP personnalisé pour décrire un comportement spécifique à l'application.

Stratégies de versionnement

Avec le temps, l'API que vous développez évoluera et vous y apporterez des modifications. C'est là que les stratégies de versionnement deviennent importantes. Vous devez vous assurer que les clients utilisant déjà vos API ne sont pas affectés par les modifications que vous apportez.

Maintenir différentes versions rendra vos API rétrocompatibles et permettra aux clients d'utiliser la version préférée de l'API en fonction de leurs besoins. Un extrait de cet article informatif sur le site de Postman explique quand il est idéal de versionner vos API :

"Vous devez versionner votre API chaque fois que vous apportez une modification qui nécessitera aux consommateurs de modifier leur base de code afin de continuer à utiliser l'API. Ce type de modification est connu sous le nom de "modification cassante", et il peut être apporté aux structures de données d'entrée et de sortie d'une API, aux retours de succès et d'erreur, et aux mécanismes de sécurité."

Le versionnement des API peut être effectué de différentes manières. Voici quelques méthodes :

  • Versionnement URI : Inclure le numéro de version dans le chemin de l'URL. Par exemple, https://api.example.com/v1/products.

  • Versionnement par paramètre de requête : Spécifier le numéro de version comme paramètre de requête dans l'URL. Par exemple, https://api.example.com/products?version=1.

  • Versionnement par en-tête : Inclure le numéro de version dans les en-têtes HTTP de la requête. Par exemple, utiliser un en-tête personnalisé comme X-API-Version: 1.

  • Négociation de contenu : Spécifier la version dans l'en-tête Accept de la requête, souvent en utilisant des types de média. Par exemple, Accept: application/vnd.example.v1+json.

  • Versionnement intégré : Intégrer le numéro de version dans le type de média de la réponse. Par exemple, application/vnd.example.product-v1+json.

Considérations de sécurité

Un autre aspect important à considérer lors du développement d'une API est la sécurité. Voici quelques points clés à retenir :

  1. Implémentez HTTPS pour chiffrer les informations échangées entre le client et le serveur.

  2. Implémentez l'authentification et l'autorisation pour vous assurer que seuls les utilisateurs disposant des privilèges appropriés peuvent effectuer des opérations sur les ressources. Les méthodes courantes incluent l'authentification de base, l'authentification par porteur ou jeton, JWT et OAuth 2.0. Implémentez également un contrôle d'accès basé sur les rôles pour gérer l'accès aux ressources.

  3. Implémentez la validation et l'assainissement des entrées pour prévenir les attaques de vulnérabilité comme l'injection SQL et le Cross-Site Scripting (XSS).

  4. Implémentez la limitation de débit et le contrôle de flux pour contrôler le nombre de requêtes qu'un client peut envoyer au serveur dans un laps de temps spécifique. Cela aide à prévenir une charge excessive sur le serveur.

Documentation

Un aspect clé mais souvent négligé du développement d'API est la documentation. Il est crucial de documenter votre API afin que les utilisateurs comprennent ses fonctionnalités.

La documentation doit être complète, facile à comprendre et suivre les pratiques standard. Incluez des exemples de corps de requête et de réponse, les codes de statut HTTP utilisés, et plus encore. Vous pouvez suivre la spécification Open API pour décrire vos API RESTful.

Stratégies de tri, de filtrage et de pagination

L'API que vous développez pourrait causer des problèmes de performance si elle retourne trop d'enregistrements. Il est inefficace de récupérer de grandes quantités de données puis de les trier ou de les filtrer.

Pour remédier à cela, vous devez permettre le tri et le filtrage des enregistrements. Vous devez également implémenter la pagination pour diviser le nombre d'enregistrements récupérés et définir une limite pour une navigation et un traitement plus faciles.

Surveillance de l'utilisation, journalisation et santé

Il est bon de journaliser vos requêtes et réponses d'API pour aider au débogage. La surveillance de l'utilisation de l'API vous aidera à comprendre les performances globales et le comportement de l'application. Effectuer des vérifications de santé régulières peut vous aider à prendre les mesures nécessaires en cas de problème. Toutes ces étapes rendront l'API plus robuste et fiable.

Conclusion

Les API, spécifiquement les API Web, sont essentielles pour que les applications logicielles communiquent sur Internet.

Cet article a expliqué ce que sont les API Web, pourquoi elles sont importantes, et différentes approches pour les développer, en se concentrant sur les API REST. Vous avez également appris des sujets clés comme la définition des ressources et des endpoints, l'utilisation des méthodes HTTP et des codes de statut standard, les stratégies de versionnement, les considérations de sécurité, la documentation, et plus encore.

Si vous avez trouvé cet article intéressant, n'hésitez pas à consulter mes autres articles sur freeCodeCamp et à me connecter sur LinkedIn.