Méthodes standard pour documenter une API RESTful

Question

Je suis en train d'écrire un cahier des charges pour une API RESTful pour une nouvelle web interne de service. Ce n'est pas très longue et assez simple, mais tout de même, c'est ma première fois avec REPOS strict (par opposition à la tricherie pour des raisons pratiques d'évitement de l' PUT et DELETE parce qu'ils sont une douleur dans le PHP, et ainsi de suite). Je me demandais si il y avait des méthodes standard ou de meilleures pratiques pour la documentation d'une interface REST? Je veux le reste de l'équipe pour comprendre en un coup d'oeil, et pour quelqu'un qui veut écrire un client pour être en mesure de le faire sans la compréhension du code sous-jacent.

Answer 1

Bien sûr, les Api REST utilise idéalement HATEOAS et être hypertexte conduit (avec une forte utilisation de types de médias), mais aussi d'avoir un simple humain respectueux de la documentation pour les développeurs de travailler hors de est utile.

Certains des outils qui sont utiles pour la production de la documentation comme ceci:

• Swagger
  • Un ouvert de spec pour la description des Api REST [ github ]
  • Outils pour l'auto-génération
    • La Documentation
    • Code pour votre API
• Mashery
  • Un projet open source [ github ]
  • Outils de génération de
    • La Documentation
    • Une exploration de l'interface de votre API
• Rucher et de l'API Plan
  • Ecrire la description de l'API dans une liste intérieure dans les démarques
  • Outils pour l'auto-génération
    • La Documentation
    • Se moquer de serveur
  • Semble focalisée sur ruby+mac devs
• RAML
  • Une spécification pour la description des Api REST [ github ]
• WADL
  • Une spécification pour l'écriture détectable API docs XML
  • Discussion la comparaison de WSDL et WADL
• APIgee
  • Un produit commercial avec certaines fonctions de documentation
• 3scale
  • Un produit commercial avec certaines fonctions de documentation

Answer 2

J'utilise http://apiary.io , ce qui est très agréable. Vous pouvez également exporter la documentation de l'API vers github.

Answer 3

Dans Roy post ici , il déclare

Une API REST devrait passer presque tous son descriptif effort dans la définition de l' le type de média(s) utilisée pour représenter les les ressources et la conduite de l'application l'état, ou dans la définition élargie concernant les noms et/ou hypertexte permis à mark-up pour les standard de types de médias. Tout l'effort dépensé décrire les méthodes à utiliser sur ce Uri d'intérêt doivent être entièrement définis dans le cadre de la les règles de traitement pour un type de média (et, dans la plupart des cas, déjà définis par les types de médias).

Answer 4

Un bon Repos de la documentation signifierait documenter votre type de média, et seul votre type de média.

Dans un scénario typique, vous souhaitez produire un document comme suit:

L'Acme Corp formats xml

Lien de la découverte Des liens vers diverses ressources sont décrites dans un document qui peut être trouvé par l'émission d'une requête GET ou HEAD pour le serveur sur un signet URI (généralement de la racine du serveur, http://www.acme.org), et à la recherche d'un Lien HTTP en-tête.

Lien: ;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

où le rel de la partie est le lien, la relation, et le xxx est l'URI pour lequel la relation a été établie.

Liens Ce document définit la relation suivante noms: http://rel.acme.org/services Le lien de la relation décrit la liste de liens qui peuvent être navigué. http://rel.acme.org/customers Le lien pour lesquels cette relation est utilisée est la liste de clients.

Types De Médias L'application/vnd.acme.services+xml est un document avec une sérialisation xml qui décrit une liste de liens, une application peut avoir besoin de processus.

L'application reposant/vnd.acme.les clients+xml est un document avec une sérialisation xml qui décrit les clients.

Exemple doucments:

etc...

Le point est de donner un moyen de le développeur à suivre les liens que vous définissez. D'abord trouver le lien vers l' index afin qu'ils puissent obtenir la liste des choses qu'ils peuvent naviguer.

Une fois qu'ils découvrent que doucment, ils découvrent qu'ils peuvent voir une liste de clients à un certain uri, et peut faire l'OBTENIR contre elle.

S'ils trouvent un client de l'intérêt, ils peuvent suivre le lien défini dans /clients/clients/@href et problème de un GET pour récupérer un represtnation de ce client.

À partir de là, votre type de média pourrait intégrer des actions qui sont disponibles pour l'utilisateur, en utilisant plus de liens. Vous avez également l'option supplémentaire de l'émission d'une demande d'OPTIONS sur la ressource pour savoir si vous pouvez vous permettre la suppression de la ressource, ou si vous pouvez enregistrer le document après modification.

Donc, un bon doucmentation ne marche jamais:

• donner le lien
• donner interaction tels que "vous pouvez émettre des POSTES Clients avec ce type de média et ce sera l'opération de déplacement". Le client doit délivrer un message contre Custoemr seulement parce que votre xml doucment a indiqué de cette façon.

Le point de tout cela est de réaliser un maximum de couplage lâche entre le client et le serveur. Le client peut être très intelligent dans l'affichage et idscovering ressources (montrant les formes et dieu sait quoi d'autre), mais est totalement muet à ce que les effectifs de flux de travail est: le serveur décide.

Answer 5

Dans mon entreprise, nous avons été très heureux à l'aide de WADL, Application Web Langage de Description. Wikipédia décrit comme: "un format de fichier XML qui fournit lisible à la machine description de HTTP applications web". Je trouve raw WADL facile à écrire, lire, comprendre, et il est associé directement à RESTful concepts. Le projet fournit un simple spec, XSD et RELAX NG schémas, et des outils Java.

Un certain nombre d'outils et de ressources existent pour travailler avec WADL, y compris:

• wadl_stylesheets, les feuilles de style XSLT pour créer la documentation HTML à partir de WADL fichiers
• Restlet, un framework Java pour la construction Reposant serveurs et des clients, comprend un WADL extension

Un conseil: essayez d'inclure lisible par l'homme, de la documentation, telles que les descriptions, concepts, mise en route, conseils d'utilisation, etc, dans le WADL du document doc de l'élément, y compris les éléments HTML, en utilisant l'espace de noms XHTML. Il peut faire une grande différence!