Documentation de l'API RESTful
Je vais bientôt concevoir une API RESTful, donc je dois la décrire afin de permettre à d'autres personnes de commencer à implémenter des clients qui l'utilisent.
J'ai regardé un peu, mais malheureusement, je n'ai trouvé aucune forme standardisée de description des services RESTful basés sur le Web. Ce que je recherche, c'est quelque chose comme JavaDoc, bien qu'il ne doive pas être généré à partir d'une sorte de code. Je ne parle pas non plus de quelque chose comme WADL, je veux plutôt avoir une documentation lisible par l'homme que je puisse distribuer.
En raison de la nature des services Web RESTful, il devrait être assez facile de standardiser une documentation. Il doit simplement lister les ressources disponibles, les URI correspondants, les méthodes autorisées, les types de contenu et décrire les actions disponibles. Avez-vous donc des suggestions?
Merci d'avance et salutations
En raison de la nature des services Web RESTful, il devrait être assez facile de standardiser une documentation. Il doit simplement lister les ressources disponibles, les URI correspondants, les méthodes autorisées, les types de contenu et décrire les actions disponibles. Avez-vous donc des suggestions?
C'est absolument la mauvaise façon de documenter les services REST.
Un URI pour les gouverner tous
Vous ne devez jamais énumérer les URI des ressources car cela encouragerait un client à coder en dur ces URI dans le code client. Cela crée un couplage inutile entre le client et le serveur. Les URI doivent être découverts en naviguant à partir de l'URI racine des services. L'URI racine est le seul URI à documenter. La documentation doit se concentrer sur la description des informations et des liens contenus dans les représentations renvoyées. Si vous commencez avec la représentation renvoyée par l'URI racine, vous pouvez décrire le type de support et quels sont les liens qui peuvent être fournis dans ce document.
Alias vos URI
Il est important d'utiliser une sorte d'alias pour créer une couche d'indirection entre le client et le serveur. Si vous suivez la norme atom: link pour définir les liens, l'attribut rel devient l'identifiant. Cependant, il existe d'autres façons de définir des liens, comme, par exemple, la façon dont les images sont incorporées en html. Une balise d'image peut avoir un identifiant et un href. La balise Id doit être utilisée pour identifier l'image pour laquelle vous souhaitez accéder à l'URL.
Les types de médias définissent votre API
Le résultat final est que vous définissez tous les points de terminaison dans votre API dans le contexte d'une représentation. L'API complète est définie par l'ensemble des représentations renvoyées et les liens qui les connectent.
Vous pouvez donc vous demander quelle est la différence? Pourquoi ne pas simplement créer la liste des points de terminaison? Voici quelques raisons,
Espace URI modifiable
Étant donné que ces liens sont accessibles par le client à l'aide d'un alias, cela permet à toute la structure d'URL de votre site d'être complètement modifiable sans impact sur le client. Cela rend toutes les questions sans fin "quelle est la meilleure façon de structurer mon URL hiérarchique" à peu près hors de propos. Vous pouvez l'essayer dans un sens, et si cela ne fonctionne pas, changez-le simplement, vous ne casserez aucun code client ou ne devrez changer aucune documentation!
Distribution dynamique
Ce n'est pas seulement la partie chemin de l'URI que vous pouvez modifier. Vous pouvez également modifier l'hôte. Imaginez que votre application commence à utiliser beaucoup plus que prévu, vous pouvez facilement changer l'hôte de toutes les ressources d'image ou vidéo pour pointer vers un autre serveur. Vous pouvez même fournir un équilibrage de charge simple en renvoyant différents hôtes. Comme les API RESTful sont sans état, peu importe le serveur qui répond à la demande. Cette fonctionnalité est utile pour de nombreux scénarios: déplacer des éléments HTTPS sur un serveur dédié, distribuer géographiquement les requêtes en fonction de l'emplacement du client, partitionner verticalement les fonctions de l'application sur différents serveurs.
Protocole explicite
Ce n'est pas parce qu'une représentation peut renvoyer un lien qu'il le sera toujours. Le serveur ne peut renvoyer que les liens autorisés en fonction de l'état actuel des ressources. Cela peut être très utile lorsqu'il existe un protocole spécifique qui doit être suivi lors de l'interaction avec une ressource serveur. Le code client n'a pas besoin de comprendre les règles du protocole, il peut simplement présenter à l'utilisateur les liens mis à disposition par le serveur.
Vous ne pouvez pas autogen les choses intéressantes
La raison pour laquelle la plupart des efforts automatisés pour documenter REST ne sont pas efficaces est que l'interface uniforme élimine le besoin de documenter les choses faciles. Une fois que vous comprenez HTTP (voir RFC2616), vous comprenez toutes les mécaniques de l'API. Il ne reste que les informations spécifiques au domaine vraiment intéressantes qui ne peuvent pas être générées.
Regardez du bon côté, la documentation devrait être beaucoup plus courte. Tout le temps disponible supplémentaire doit être consacré à fournir des exemples de navigation dans l'API pour les scénarios courants.
Il n'y a pas de norme, juste un débat ouvert. Il y a un article intéressant sur InfoQ: Décrire les applications RESTful .
Si vous utilisez quelque chose comme JAX-RS vous pouvez utiliser le JavaDoc réel de l'implémentation comme référence. Ou faire une analyse d'annotation et la générer automatiquement ne devrait pas être trop difficile aussi, bien que je ne connaisse pas une implémentation spécifique.