Une API est une interface de programmation pour la communication entre des applications ou des composants. Les API sont divisées en privées et publiques. Les API privées sont utilisées au sein d'une entreprise si, par exemple, elle dispose de plusieurs produits logiciels qui communiquent entre eux. Les API publiques peuvent être utilisées par des développeurs tiers. Certes, dans certains cas, vous devez payer pour cela. Mais les exigences des utilisateurs en matière de qualité et de convivialité de l'API seront également plus élevées.
Lorsque les services API deviennent publics, aucun miracle ne se produit. Le nombre d'utilisateurs n'augmente pas, et vous pouvez généralement oublier de rendre cette fonctionnalité payante (nous excluons les cas où le produit est promu en raison de mensonges marketing avec une publicité agressive).
Et si les revenus de l'entreprise dépendent directement de l'API publique, alors les enjeux sont vraiment importants. Cette idée est discutée plus en détail dans le livre « API Continuous Development. Les bonnes décisions dans un paysage technologique en mutation » (Mehdi Medjui, Ronnie Mitra, etc.) :
et nous irons plus loin... Les
développeurs peuvent principalement se concentrer sur l'implémentation de toutes les fonctionnalités prévues dans l'API. Mais il existe des exigences « non fonctionnelles » qui ne sont souvent pas entièrement satisfaites et nécessitent une attention particulière.
À mon avis, pour toutes les API, il est impératif que les exigences non fonctionnelles suivantes soient satisfaites avec une bonne qualité :
- Sécurité
- Documentation
- Validation
- Essai
Sécurité
Cela ne vaut probablement pas la peine d'expliquer pourquoi la sécurité est la priorité. J'ai identifié quatre des défis de sécurité les plus importants :
- Utiliser HTTPS avec des certificats SSL
- Partage de ressources de différentes sources (CORS)
- Authentification et jetons Web JSON
- Autorisation et privilèges d'accès
* Ci-après, nous allons restreindre le contexte aux API REST et JSON.
1. Utiliser HTTPS avec des certificats SSL
HTTPS utilisant des certificats SSL est désormais la norme de sécurité de facto. Pour générer des certificats, j'utilise personnellement Let's Encrypt , une autorité de certification gratuite et automatisée de l'Internet Security Research Group (ISRG) à but non lucratif.
Ces certificats garantissent que les données allant de votre API à l'utilisateur sont cryptées.
2. Partage de ressources provenant de différentes sources (CORS)
Pour sécuriser les requêtes vers d'autres sources, les navigateurs utilisent un mécanisme appelé CORS. CORS signifie Cross-Origin Resource Sharing, une technologie permettant de partager des ressources provenant de différentes sources. Bien que les navigateurs (en vertu de la même règle de source) n'autorisent pas l'accès aux ressources provenant de sources différentes, CORS vous permet de contourner ces restrictions et en même temps de garantir que l'accès aux ressources est sécurisé.
Les agents utilisateurs (par exemple, les navigateurs), sur la base des valeurs des en-têtes supplémentaires pour CORS dans la requête HTTP, peuvent envoyer des requêtes à d'autres sources qui seraient bloquées sans CORS.
Voici un exemple : Une
page HTML servie par un serveur de http://domain-a.com demande src à http://domain-b.com/image.jpg .
De nombreuses pages chargent des ressources telles que des styles CSS, des images et des scripts de différents domaines correspondant à différents CDN (Content Delivery Networks). L'
implémentation de CORS pour Node.js est très populaire aujourd'hui .
3. Authentification et jetons Web JSON (JWT)
Il existe plusieurs approches pour l'authentification des utilisateurs API, mais l'une des meilleures est l'utilisation de JWT. Ces jetons sont signés à l'aide de divers algorithmes cryptographiques.
JSON Web Token est un standard ouvert pour la création de jetons d'accès basés sur le format JSON. Généralement utilisé pour transmettre les données d'authentification dans les applications client-serveur.
Pour créer un jeton, vous devez définir un en-tête avec des informations générales sur le jeton, la charge utile, telles que l'ID utilisateur, le rôle, etc., ainsi que les signatures. En termes simples, JWT n'est qu'une chaîne au format suivant : header.payload.signature.
Lorsque le client se connecte, le service de gestion des identités fournit le JWT au client. Le client peut ensuite utiliser ce jeton pour effectuer des requêtes API. L'API a accès à une clé publique ou à un secret qu'elle utilise pour valider le jeton.
Pour vérification, vous pouvez utiliser, par exemple, la bibliothèque jsonwebtoken . Vous trouverez ci-dessous le code JavaScript :
import jwt from 'jsonwebtoken'
export default function (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken (req)
jwt.verify (token, SECRET, {algorithms : ['HS256']}, (err, décodé) => {
the if (err) {next (err)}
req.session = Decoded
next ()
})
}
Plus d'informations sur JWT, les bibliothèques et les langages de programmation pris en charge - en ligne JWT.io .
4. Autorisation et privilèges d'accès
L'authentification est importante, mais l'autorisation l'est tout autant : un client qui s'est authentifié et a reçu le JWT a-t-il le privilège d'exécuter une requête particulière ?
Pour tester cela, nous utilisons un scope. En l'analysant, le service API détermine si cette demande client peut être satisfaite sans recherches ACL coûteuses.
La portée est un bloc de texte (généralement séparé par des espaces) qui décrit les privilèges d'accès d'un point de terminaison d'API. Il décrit les Ressources et les Actions qui peuvent leur être appliquées. Cette formalisation fonctionne bien pour les API REST / JSON car leur structure est très similaire.
RESSOURCE : ACTION (par exemple, ARTICLE : ÉCRIRE ou ARTICLE : LIRE, où ARTICLE est une ressource et LECTURE et ÉCRITURE sont des actions).
Cela permet aux développeurs d'API de se concentrer sur les fonctionnalités plutôt que sur les rôles ou les utilisateurs. Le service de gestion des identités peut associer des rôles et des utilisateurs à des étendues spécifiques, puis, avec le JWT, envoyer l'étendue au client.
Dormir calmement
Lors du développement et du déploiement d'API, la sécurité doit toujours être l'une des exigences les plus importantes. Bien sûr, vous pouvez en parler et écrire à l'infini, mais la mise en œuvre compétente des quatre tâches décrites en production vous permettra déjà de bien dormir.
Documentation
Quoi de pire qu'un manque de documentation ? Documentation obsolète !
Les développeurs sont ambigus sur la documentation. Beaucoup n'ont clairement pas beaucoup d'amour pour cette entreprise. Quoi qu'il en soit, cette tâche est très importante - surtout en ce qui concerne l'API publique. Les développeurs tiers devraient être capables d'apprendre à l'utiliser. De plus, une bonne documentation vous aidera à former plus rapidement de nouveaux développeurs qui rejoignent votre équipe.
La documentation de l'API doit inclure trois sections de base :
- Présentation (LISEZ-MOI)
- Fiche technique (Spécifications)
- Exemples d'utilisation (Mise en route et autres sous-sections similaires)
1. LISEZ-MOI
La documentation doit vous expliquer à quoi sert l'API, comment configurer l'environnement, comment tester le service, comment déployer le projet. Bien entendu, les utilisateurs doivent également savoir comment et où signaler des difficultés ou des problèmes.
Ceci est écrit dans le fichier README. Ce fichier est généralement également placé dans le référentiel, il donne aux développeurs un point de départ pour travailler avec votre projet.
Le fichier README doit contenir :
- Description de l'API
- Liens vers des références techniques et des manuels
- Guide de configuration du développeur
- Guide du testeur
- Guide de déploiement
- Gestion des dépendances
- Guide des contributeurs
- Code de conduite
- Licence
- Merci
Soyez concis dans votre README ; vous n'avez pas besoin d'expliquer toutes les nuances, mais de fournir suffisamment d'informations pour que les développeurs se plongent dans votre projet.
2. Spécifications
Dans l'API REST / JSON, chaque point de terminaison est une fonction conçue dans un but spécifique. Il est important d'avoir une documentation technique qui décrit chaque point de terminaison, les entrées et les sorties, et comment le service fonctionne avec différents clients.
Vous pouvez créer votre propre documentation API basée sur OpenAPI .
Il s'agit d'une spécification et d'un cadre complet pour décrire, créer, consommer et rendre des services Web REST. Son travail est de permettre aux systèmes de documentation de synchroniser leurs mises à jour avec les changements sur le serveur. Les méthodes, paramètres, modèles et autres éléments sont intégrés au logiciel serveur via OpenAPI et sont synchronisés avec lui en permanence.
3. Exemples d'utilisation
Il est peu probable que les utilisateurs de votre API soient satisfaits si vous leur jetez simplement les spécifications. Ils veulent savoir comment utiliser votre API dans des situations spécifiques et comment résoudre les problèmes courants. La plupart des utilisateurs potentiels ont des problèmes et ils se tournent vers votre API pour les résoudre.
Un excellent moyen de présenter votre API aux utilisateurs est de créer une sous-section Mise en route. Cela vous aidera à comprendre les cas d'utilisation typiques et à les utiliser pour évaluer les avantages de votre API.
Trois baleines
La documentation est un élément clé de toute API. Lors de la rédaction de la documentation, gardez à l'esprit les trois piliers d'une documentation API réussie : les README, les spécifications et les cas d'utilisation. Et vous (et vos utilisateurs) serez heureux !
La validation des données
Un aspect important du développement d'API, la validation des données, est souvent négligé par beaucoup. La validation est le processus de validation des entrées provenant de sources externes. Ces sources peuvent être un client envoyant du JSON ou un service répondant à votre demande. Cette vérification permettra de s'assurer que les données sont exactement comme il se doit. Grâce à cela, vous pouvez éliminer de nombreux problèmes potentiels. Une tâche importante de validation est de comprendre quel format et quelle plage de valeurs les données d'entrée doivent avoir et comment les contrôler.
La meilleure stratégie consiste à exécuter la validation avant que votre service n'effectue toute manipulation de données. Lorsqu'un client envoie ses données à votre API, telles que l'e-mail, la date et le nom, assurez-vous qu'il s'agit bien d'une adresse e-mail, que la date est correctement formatée et que la chaîne répond aux exigences de longueur. Cette simple vérification rendra votre service plus sécurisé et organisé.
De plus, lorsque vous obtenez des données d'un service, d'une sorte de base de données ou de cache, vérifiez-les à nouveau pour vous assurer que le résultat renvoyé est comme prévu.
Vous pouvez implémenter la validation à la main, mais des bibliothèques telles que Lodash ou Ramda peuvent également être utilisées à cette fin .... Ils sont parfaits pour les petits objets de données. Les bibliothèques comme Joi , Yup ou Zod fonctionnent encore mieux car elles vous permettent de décrire un cadre de validation général, ce qui vous fait gagner du temps et des efforts. Si vous avez besoin de quelque chose d'indépendant d'un langage de programmation particulier, jetez un œil à JSON Schema .
Mieux vaut le garder à l'écart
La validation n'est guère passionnante, mais elle peut vous faire gagner beaucoup de temps qui serait autrement consacré au dépannage et à l'écriture de scripts de migration de données. Ne faites pas l'erreur de faire confiance à votre client pour envoyer des données non vérifiées si vous ne voulez pas que de mauvaises données se retrouvent dans votre logique métier ou votre stockage.
Prenez le temps et organisez la validation de votre entrée. Comme dit le proverbe, il vaut mieux en faire trop que de le rater.
Essai
Les tests font partie intégrante du cycle de vie du logiciel. Dans notre cas, cela devrait être perçu comme l'une des exigences non fonctionnelles clés. Définir une stratégie de test peut être une tâche ardue pour tout projet, y compris une API de service. Essayez toujours d'être conscient de vos limites et de définir votre stratégie en conséquence.
Les tests d'intégration sont l'une des méthodes de test d'API les plus efficaces. Sa tâche est de vérifier que l'application passe correctement d'un état à un autre. Dans notre cas, l'ensemble des tests d'intégration devrait inclure le test des points d'entrée de l'API de service, ainsi que des maquettes pour simuler l'envoi d'une requête et la réception d'une réponse. C'est ainsi que nous vérifions le cas de test principal de notre service.
Cette méthode vous permet de vous concentrer uniquement sur la logique de traitement des données, sans tenir compte des éléments internes des services backend ou de la logique de présentation des données. L'absence de dépendances rend l'exécution des tests plus fiable, plus facile à automatiser et plus facile à intégrer dans un pipeline d'intégration continue.
Pour les tests d'intégration, j'utilise Tape , Test-server et Fetch-mock . Ces bibliothèques vous permettent d'exécuter des tests isolés sur des points de terminaison d'API, allant de la demande à la réponse.
Jeu d'imitation
D'autres types de tests et de vérification de type sont certainement également utiles, les tests d'intégration présentant le plus grand avantage : ils sont très efficaces et nécessitent moins d'heures de travail pour l'écriture et la maintenance des tests. Et l'utilisation d'outils comme Fetch-mock peut fournir une simulation complète de l'échange de données.
Ne t'arrête pas là
Une fois que vous avez rempli les quatre exigences non fonctionnelles, ne vous arrêtez pas là. Il y en a quelques autres : la surveillance des applications, la journalisation et la gestion des API. Mais dans tous les cas, la sécurité, la documentation, la validation et les tests doivent passer en premier.
Les serveurs cloud de Macleod sont rapides et sécurisés.
Inscrivez-vous en utilisant le lien ci-dessus ou en cliquant sur la bannière et bénéficiez d'une remise de 10 % pour le premier mois de location d'un serveur de n'importe quelle configuration !
