Il y un an et demi environ, nous avons eu l’idée de proposer un travail sur les bonnes pratiques concernant les API (Interfaces de programmation). Olivier Meunier avait posé quelques jalons avec une comparaison de l’implémentation de Rest avec xmlHTTPrequest dans quelques navigateurs. La création de la check-list en elle-même a été initiée au cours d’une séance de travail à Paris. Un peu plus tard, nous avons proposé à d’autres de nous rejoindre autour d’un document en ligne. Il s’agit d’un travail préparatoire. J’aimerais avoir votre avis sur l’intérêt et la nécessité d’une telle check-list dans le cadre du projet Opquast.
Voici les premières idées qui sont arrivées :
- Les actions provoquées par les verbes utilisés sont cohérentes avec le verbe en question
- Toute action utilisant POST correspond à la création d’une ressource
- Toute action utilisant PUT correspond à la modification d’une ressource
- Toute action utilisant DELETE correspond à la suppression d’une ressource
- Les actions GET ne modifient pas l’état de la ressource
- Le format n’est pas spécifié dans l’URL de la ressource
- Le service accepte les en-têtes accept
- Le service sert les formats en fonction de ce qui est spécifié dans les en-têtes clients
- Chaque ressource fait l’objet d’un id unique
- Chaque ressource est identifiable avec une URI
- Les demandes d’en-têtes incorrectes ou manquantes donnent lieu à une réponse X
- Les réponses à une requête de type GET pour une ressource existante ont un statut 200
- Les réponses à une requête de type GET pour une ressource inexistante ont un statut 404
- Les requêtes avec une méthode non supportée donnent lieu à une réponse 405
- Une requête de type OPTIONS donne lieu à l’envoi d’une liste de méthodes acceptées
- La création immédiate d’une ressource donne lieu à l’émission d’une réponse de statut 201 ou 303
- La création immédiate d’une ressource déclenche l’envoi d’une réponse contenant un en-tête location
- Chaque en-tête location correspond soit à la ressource, soit à l’URI permettant de la suivre
- Les url ne contiennent pas de paramètres de versions
- Les requêtes nécessitant une authentification alors que le client n’est pas authentifié donnent lieu à une réponse 401
- Les requêtes vers une ressource protégée/privée alors que le client est authentifié donnent lieu à une réponse 403
- Les requêtes PUT permettent de modifier ou créer une ressource en envoyant une représentation complète
- Les requêtes PATCH permettent de modifier une ressource en envoyant une représentation partielle
- oAuth1 est supporté pour l’authentification
- oAuth2 est supporté pour l’authentification
- HTTP Basic est supporté pour l’authentification
- Les requêtes authentifiées sont uniquement supportées sur HTTPS
- JSON ou XML est supporté comme format
- Une politique ‘Access Control’ est définie
Merci à Karl, François, Laurent, Olivier, Fabrice et ceux qui ont contribué à cette première liste.
Alors, avez-vous envie de jouer avec nous ? Avez-vous d’autres idées ? Seriez-vous partant pour un nouvel atelier Opquast ?
P.S. : si ce sujet vous intéresse, rendez-vous à la mini-conférence Bonnes pratiques API d’Eric Daspet à ParisWeb
4 commentaires sur “Bonnes pratiques qualité API-REST”
Les commentaires sont clos..
Bon début.
Existe-t-il une liste des bonnes pratiques HTTP ?
Dans cette liste au dessus, il y a des éléments qui sont purement HTTP, d’autres API. Je n’ai pas trouvé d’éléments spécifiquement REST. Il y en a aussi certaines que je n’ai comprises.
Peut-être faut-il éviter le mot REST et ne pas mettre mettre le mot API en importance afin d’éviter les emmerdeurs de mon type 😉
Suggestion : Bonnes pratiques qualité pour la création d’une API utilisant HTTP
Si nous parlons de REST, il faudra donner des règles pour le client également, car tout l’intérêt de REST est entre le dialogue client-serveur. Si le client est neutre, il n’y a plus vraiment de REST. On peut penser par exemple à l’exploration des liens et des rels.
À propos de l’intérêt :
« J’aimerais avoir votre avis sur l’intérêt et la nécessité d’une telle check-list dans le cadre du projet Opquast. »
Tout dépend du public visé. Si c’est pour améliorer la qualité du travail du développeur, il faudra surement définir cette liste sous une forme test-driven. C’est à dire créer les instances client et serveurs afin de pouvoir tester l’ensemble. Il y a plus de chances de convaincre. Il faudrait aussi que ceux qui développent une API s’exprime. Le danger est que la liste soit utilisée par un chef de projet venant assassiner le développeur sans comprendre ce qu’il demande. Notamment pour la partie « REST » suggérée. REST est un style.
En tout cas excellent d’avoir démarré la liste car cela donne de la matière à méditer pour les randonnées nocturnes sous la lune.
J’en suis 🙂
À vue de nez, les actions de POST et PUT sont inversées.
« Toute action utilisant POST correspond à la création d’une ressource
Toute action utilisant PUT correspond à la modification d’une ressource »
Olivier en fait, ni l’un ni l’autre.
POST est une création, mise à jour dont le serveur contrôle la mécanique.
PUT est une création, mise à jour dont le client contrôle la mécanique.