À retenir
- Concevoir autour des ressources et de conventions claires et cohérentes.
- Authentifier chaque requête et autoriser chaque action.
- Versionner délibérément et ne jamais casser silencieusement les consommateurs existants.
- Documenter avec des exemples et superviser comme un produit.
Une API est un produit destiné aux développeurs. Une checklist pratique pour concevoir, sécuriser, versionner et exploiter des API REST en lesquelles les intégrateurs ont confiance.
Concevoir pour ceux qui l'appelleront
Les bonnes API sont prévisibles. Utilisez des noms pour les ressources, les méthodes et codes HTTP standard, un nommage cohérent et un format d'erreur unique. Un développeur qui comprend un endpoint doit pouvoir deviner comment fonctionne le suivant.
- Nommage et pluriel des ressources cohérents.
- Pagination, filtrage et tri sur chaque endpoint de liste.
- Un corps d'erreur standard avec code, message et détails.
- Des clés d'idempotence pour les opérations qui créent des paiements ou des commandes.
La sécurité à chaque requête
Authentifiez chaque appel – généralement avec OAuth 2.0 ou des jetons signés – et autorisez chaque action selon le rôle et le périmètre de l'appelant. Validez les entrées à la frontière, limitez la taille des requêtes et le débit des clients pour qu'une intégration ne puisse pas épuiser le service.
Versionner sans casser les consommateurs
Les changements additifs – nouveaux champs, nouveaux endpoints – ne devraient casser personne. Supprimer ou renommer des champs, si. Versionnez l'API explicitement, annoncez les dépréciations tôt et maintenez les anciennes versions jusqu'à ce que les consommateurs aient migré.
Documentation et expérience développeur
Une spécification OpenAPI générée à partir du code garde la documentation exacte. Ajoutez des exemples de requêtes et de réponses, des instructions d'authentification et un environnement bac à sable pour que les intégrateurs puissent tester en sécurité.
L'exploiter comme un produit
Les API qui durent sont celles dont les responsables savent comment elles sont utilisées – et remarquent vite quand quelque chose ne va pas.
- Suivre la latence et le taux d'erreur par endpoint et par client.
- Journaliser les identifiants de requête pour tracer les problèmes de bout en bout.
- Utiliser des webhooks avec relances et signatures pour les notifications d'événements.
- Publier un statut et un changelog pour les consommateurs.
Cet article vous a plu ? Recevez le prochain par e-mail.