La plupart des interfaces de repos que je vois sont décrites avec une simple page Web décrivant l'URL, la méthode, l'entrée acceptée et le résultat renvoyé. Par exemple, le Amazon S3 ou le Twitter API Documentation.
L'homme lisible est apparemment assez bon pour Amazonon ou Twitter. Cependant, y a-t-il des entreprises décrivant une API de repos dans un format lisible par machine? Et si oui, lesquels?
Les revendications WSDL 2.0 sont capable de décrire le repos . WADL est explicitement créé pour décrire les services de repos. WSDL 2.0 et WADL semblent avoir un guichet automatique assez petit et semblent être peu de retour pour l'effort de création et de maintien des documents de description. En identifiant des exemples de vie réels, il est essentiellement possible de valider ou de nier cette hypothèse.
Utilisez-vous WSDL / WADL pour décrire vos services? Vous comptez-vous sur WSDL / WADL pour consommer les services des autres? Votre outil de choix apporte-t-il l'un ou l'autre pour le moment? Y a-t-il des exemples de services de repos largement utilisés pouvant être utilisés détaillés dans un format lisible par machine?
5 Réponses :
Ce qui suit est juste mon opinion personnelle:
Je pense que Wadl est similaire aux cartes du site pour les pages HTML. Les cartes du site sont considérées comme théoriquement une bonne pratique, mais rarement mises en œuvre et encore plus rarement utilisées par les gens.
Je pense que la raison est simple - errant autour d'un site et poussant des boutons placés de manière stratégique est souvent significativement plus gratifiant que de naviguer sur une carte complexe.
Les méthodes API de repos ne doivent pas nécessiter une description formelle. Donc, si l'API est créée pensivement, il est assez facile de découvrir toutes les ressources simplement en suivant des liens URI stratégiquement placés d'une ressource reposante «Home».
Votre réponse est correcte dans l'esprit. Une interface de repos doit être découverte comme vous le décrivez. Cependant, tous les types de médias utilisés par les représentations devraient avoir des définitions formelles. Le repos n'est pas une excuse éviter de documenter votre API. La différence est ce que vous documez. Documez-vous les structures de données qui circulent entre le client et le serveur, tout simplement pas les points finaux (c.-à-d. URL).
Quel est l'avantage d'une définition d'API de repos lisible par la machine?
Le point de repos est que l'API soit relativement simple et facile à comprendre. La langue naturelle fonctionne bien pour cela.
Si vous voulez dire "Définitions de type API" lorsque vous dites "Définition de l'API", il peut y avoir une certaine valeur dans la fourniture de métadonnées. Cela n'est cependant qu'un seul morceau d'une définition de l'API.
Avoir une API "machine lisible" peut facilement répéter le code source de l'API, enfreindre le principe sec.
Il est souvent plus simple d'écrire des descriptions en anglais de ce que font les verbes de repos et de ce que sont les Uri. Envoyez les types de type via JSON (ou YAML ou JAXB) comme code source. C'est l'API parfaite lisible à la machine - Source de travail réelle pour la classe d'objets de message.
Les définitions lisibles de la machine sont utiles pour définir des types et un autre code de support dans diverses langages de programmation.
Il y a un phénononon de poulet / d'œuf ici. Wadl est inutile sans outils qui le produisent ou le consomment. Les outils sont inutiles à moins que les sites publient Wadl. etc.
Pour moi, le modèle Amazon fonctionne bien. En fonction de votre public, vous obtiendrez plus de retour sur un effort pour produire des échantillons, y compris des dialogues d'échantillons OD de Snips OD (à quoi Demande1 ressemble-t-on sur le fil, identique à la réponse 1, puis demande 2, réponse 2, etc.), etc.) et code dans VVarious langues qui sont importantes pour vous. Si vous souhaitez aller à une définition lisible par la machine, vous pouvez utiliser XSD s'il s'agit d'un format de message XML. Évidemment, ce n'est pas Wadl mais couplé à votre description en anglais, cela peut fournir un petit utilitaire supplémentaire pour les développeurs.
Oui, vous devriez. Vous serez en mesure de générer votre code client, vos tests et votre documentation à l'aide d'un ensemble d'outils prenant en charge WADL. Certains exemples peuvent être trouvés ici . De plus, je pense que vous devriez rester avec Wadl, plutôt que WSDL 2.0 car il est moins Verbose et Way Simpler (IMHO). En fait, dans Wadl, vous décrivez exactement ce que l'utilisateur voit sur la page de documentation, à l'aide de la syntaxe Wadl XML. BTW, c'est pourquoi il est si facile d'écrire des générateurs de documentation basés sur XSLT pour WADL.
L'utilisation la plus populaire de WSDL (et Wadl de la même manière) est la génération de code. Il contribue certainement à accélérer le développement, mais rien ne peut remplacer une ancienne documentation simple. Pour les humains et non pour les machines.
Voir la question similaire Stackoverflow.com/ Questions / 1312087 / ...
Cette question est également pertinente: Stackoverflow.com/questions/33775770/...