Bonnes pratiques qualité API-REST

Par Élie Sloïm, le 2 octobre 2013, dans Opquast - Actualités.

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