En raison de la nature de RESTful web
services, il devrait être assez facile de
normaliser une documentation. Il devrait
juste la liste des ressources disponibles,
correspondant Uri, méthodes autorisées,
des types de contenu et de décrire les
disponible actions. Vous disposez de tous
suggestions par conséquent?
Ce n'est absolument pas la voie à suivre sur la documentation des services REST.
Un URI pour les gouverner tous
Vous ne devriez jamais énumérer les Uri des ressources parce que ce serait encourager un client à coder en dur ces URIs dans le code client. Cela crée inutile de couplage entre le client et le serveur. Uri doit être découvert basée sur la navigation à partir de la racine des services d'URI. La racine de l'URI est le seul URI qui devraient être documentées.
La documentation devrait se concentrer sur la description de ce que les informations et les liens sont dans les représentations qui sont renvoyés. Si vous commencez avec de la représentation, qui est retourné à partir de la racine URI, vous pouvez décrire le type de support et quels sont les liens qui peuvent être fournis dans ce document.
Alias de votre 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 les atom:link standard pour la définition des liens, puis l'attribut rel devient l'identificateur. Cependant, il existe d'autres façons de définir des liens, comme, par exemple, la façon dont les images sont intégrées dans le code html. Une balise d'image peut avoir un Id et un href. L'Id de la balise doit être utilisé pour identifier l'image que vous souhaitez accéder à l'URL.
Les types de médias à définir votre API
Le résultat final est que vous pouvez définir tous les paramètres de votre API dans le contexte d'une représentation. La complète de l'API est définie par l'ensemble des retournés représentations et les liens qui les unissent.
Ainsi, vous pouvez demander, quelle est la différence? Pourquoi ne pas simplement créer la liste des points de terminaison? Voici quelques raisons,
Variable URI de l'espace
Parce que ces liens sont accessibles par le client à l'aide d'un alias, cela permet à l'ensemble de la structure de l'URL de votre site afin d'être complètement modifiables, sans impact sur le client. Cela rend l'ensemble de l'infini "quelle est la meilleure façon de structurer mes hiérarchique URL" questions assez bien hors de propos. Vous pouvez essayer une façon, et si ça ne fonctionne pas, il suffit de changer, vous ne serez pas tout casser code client ou d'avoir à changer toute la documentation!
De distribution dynamique
Il n'est pas juste le chemin partie de l'URI que vous pouvez modifier. Vous pouvez également changer l'hôte. Imaginez que votre application est en train de devenir beaucoup plus l'utilisation que vous l'aviez prévu, vous pouvez facilement changer l'hôte de l'ensemble de l'image ou de la vidéo de ressources pour pointer vers un serveur différent. Vous pouvez même offrir une simple équilibrage de charge par le retour des hôtes différents. Comme RESTful Api sont apatrides, il n'a pas vraiment d'importance quel serveur répond à la requête. Cette fonctionnalité est utile pour de nombreux scénarios: le déplacement HTTPS trucs sur un serveur dédié, la distribution géographique des demandes basées sur la localisation des clients, à la verticale de partitionnement des fonctions de l'application sur les différents serveurs.
Explicite protocole
Simplement parce qu'une représentation peut renvoyer à un lien, ne signifie pas qu'il le sera toujours. Le serveur peut renvoyer uniquement les liens qui sont autorisées en fonction de l'état actuel de la ressource. Cela peut être très utile quand il y a un protocole spécifique qui doit être suivie lors de l'interaction avec un serveur de ressources. Le code client n'a pas besoin de comprendre les règles du protocole, elle peut présenter à l'utilisateur les liens qui ont été mis à disposition par le serveur.
Vous ne pouvez pas autogen les choses intéressantes
La raison pourquoi la plupart des automatisé efforts pour documenter RESTE services ne sont pas efficaces, c'est parce que l'interface uniforme supprime la nécessité de documenter les choses faciles. Une fois que vous comprenez HTTP (voir la RFC2616) de comprendre l'ensemble des mécanismes de l'API. Tout ce qui est à gauche est vraiment intéressante domaine de l'information spécifique qui ne peut pas être généré.
Look on the bright side, la documentation devrait être beaucoup plus court. Supplémentaire disponibles, le temps devrait être consacré à fournir des exemples de la façon de naviguer dans l'API pour les scénarios courants.
