Jforex Api Dokumentationsstandard

Im Schreiben einer Spezifikation für eine RESTful API für einen neuen internen Webdienst. Es ist nicht sehr lang und ziemlich einfach, aber auch so, es ist mein erstes Mal mit strengen REST (im Gegensatz zu Betrug aus praktischen Gründen - zu vermeiden PUT und DELETE, weil sie ein Schmerz in PHP, und so weiter). Ich frage mich, ob es irgendwelche Standardmethoden oder Best Practices für die Dokumentation einer REST-Schnittstelle Ich möchte, dass der Rest des Teams, um es auf einen Blick zu verstehen, und für alle, die einen Client zu schreiben, um dies ohne Verständnis der zugrunde liegenden schreiben möchte Code. Dass die REST-API fast alle ihre beschreibenden Anstrengungen verbringen sollte, um die Medienart (en) zu definieren, die für die Darstellung von Ressourcen und das Ansteuern des Anwendungszustands verwendet wird, oder bei der Definition von erweiterten Beziehungsnamen und / oder Hypertext Aktivierung für vorhandene Standardmedientypen. Jegliche Bemühungen, die beschreiben, welche Methoden zu verwenden, welche URIs von Interesse sollte vollständig im Rahmen der Verarbeitungsregeln für einen Medientyp (und in den meisten Fällen bereits definiert durch bestehende Medientypen) definiert werden. Beantwortet Mai 22 09 at 17:11 Gotcha. Das war auch mein Bauchgefühl: Erklären Sie ausführlich, was jeder Anruf tut. Nicht, was es ist. Ich denke, es gibt keine Standardmethode dafür, aber die Hölle, ich schätze, dass es nie jemanden verletzt (don39t zitiere mich darauf). Danke für Ihre Hilfe. Ndash Samir Talwar Sure, REST-APIs sollten idealerweise verwenden HATEOAS und hypertextgetrieben (mit starken Einsatz von Medientypen), sondern auch mit einfachen menschlichen Dokumentation für Entwickler zu arbeiten, ist hilfreich. Einige spezifische Werkzeuge, die für die Erstellung von Dokumentationen wie diese hilfreich sind: Swagger Eine offene Spezifikation für die Beschreibung REST-APIs github Tools für die automatische Generierung von Dokumentations-Code für Ihre API Mashery Ein Open-Source-Projekt github Tools für die Erstellung von Dokumentationen Eine Explorationsschnittstelle für Ihre API-Apiary und API Blueprint Schreiben Sie die API-Beschreibung in eine DSL innerhalb markdown Tools für die automatische Generierung von Dokumentationen Mock-Server Scheint auf rubymac devs konzentriert RAML Eine Spezifikation für die Beschreibung REST APIs github WADL Eine Spezifikation für das Schreiben von API-Dokumenten mit XML Einige Diskussion Vergleich WSDL und WADL-APIgee Ein kommerzielles Produkt mit einigen Dokumentationsmerkmalen 3scale Ein kommerzielles Produkt mit einigen Dokumentationsmerkmalen miredot kommerziellen REST API-Dokumentationsgenerator Java spezifische Antwort # 1 am: 13:44 In meinem Unternehmen waren wir sehr glücklich mit WADL. Web-Anwendungsbeschreibung Sprache. Wikipedia beschreibt es als: ein XML-basiertes Dateiformat, das eine maschinenlesbare Beschreibung von HTTP-basierten Web-Anwendungen bereitstellt. Ich finde rohe WADL einfach zu schreiben, zu lesen und zu verstehen, und es Karten direkt zu RESTful Konzepte. Das offizielle Projekt bietet eine einfache Spezifikation, XSD und RELAX NG-Schemata und Java-Tools. Für die Arbeit mit WADL gibt es eine Reihe von Tools und Ressourcen, darunter: wadlstylesheets. XSLT Stylesheets erstellen HTML-Dokumentation aus WADL-Dateien Restlet. Ein Java-Framework für den Aufbau von RESTful-Servern und - Clients, beinhaltet eine WADL-Erweiterung. Ein Tipp: Versuchen Sie es mit menschenlesbaren Dokumentationen wie Beschreibungen, Konzepten, Erste-Hilfe-Tipps, etc Der XHTML-Namespace. Es kann einen großen Unterschied geantwortet werden Ich habe in WADL schaute, aber es scheint, dass es39s eher in Richtung Maschine Interpretation eher als Dokumentation. Ich don39t Notwendigkeit, dem Computer zu erklären, wie man mit der API umgibt -, die nur einmal geschrieben werden muss. Ich muss den Leuten sagen, wie man Kunden schreibt, und so sind die Leute mein primäres Publikum. Ndash Samir Talwar May 22 09 at 20:59 Eine gute ReST-Dokumentation würde bedeuten, dokumentieren Sie Ihre Medientyp und nur Ihre Medientyp. In einem typischen Szenario erstellen Sie ein Dokument wie folgt: Die Acme Corp-XML-Formate Link Discovery-Links zu verschiedenen Ressourcen werden in einem Dokument beschrieben, das gefunden werden kann, indem eine GET - oder HEAD-Anfrage an den Server auf einem Lesezeichen-URI (typischerweise root) ausgegeben wird Des Servers, acme. org) und sucht nach einem HTTP-Link-Header: wobei der rel-Teil die Link-Beziehung ist und xxx der URI ist, für den die Beziehung hergestellt wurde. Link Beziehungen Dieses Dokument definiert die folgenden Beziehungsnamen: rel. acme. orgservices Die Link-Beziehung beschreibt die Liste der Links, die navigiert werden können. Rel. acme. orgcustomers Der Link, für den diese Beziehung verwendet wird, ist die Liste der Kunden. Medientypen Die applicationvnd. acme. servicesxml ist ein Dokument mit einer XML-Serialisierung, die eine Liste von Links beschreibt, die eine Anwendung möglicherweise verarbeiten möchte. Die applcationvnd. acme. customersxml ist ein Dokument mit einer XML-Serialisierung, die Kunden beschreibt. Beispieldokumente: Der Punkt ist, dem Entwickler eine Möglichkeit zu geben, den von Ihnen definierten Links zu folgen. Erstens finden Sie den Link zum Index, so dass sie die Liste der Dinge, die sie zu navigieren bekommen können. Sobald sie dieses Dokument entdecken, entdecken sie, dass sie eine Liste der Kunden bei einem bestimmten Uri sehen können, und können einen GET dagegen tun. Wenn sie einen Kunden von Interesse finden, können sie dem in customerscustomerhref definierten Link folgen und ein GET abgeben, um eine Repräsentation dieses Kunden abzurufen. Von dort aus könnte Ihr Medientyp Aktionen einbetten, die dem Benutzer zur Verfügung stehen, wobei mehr Links verwendet werden. Sie haben auch die zusätzliche Option, eine OPTIONS-Anfrage auf die Ressource zu senden, um zu wissen, ob Sie das Löschen der Ressource zulassen können, oder ein PUT, wenn Sie das Dokument nach der Änderung speichern können. Also eine gute Dokumentation nicht immer: geben Sie statische Links geben Interaktion wie Sie POST auf Kunden mit diesem Medientyp ausgeben können und das wird der Verschiebung Betrieb bedeuten. Der Client sollte einen POST gegen den Kunden ausgeben, nur weil Ihr XML-Dokument es so spezifiziert hat. Der Punkt von all dem ist es, eine minimale Kopplung zwischen Clients und Servern zu erreichen. Der Client kann sehr schlau in der Anzeige und Entdeckung von Ressourcen (Formulare und Gott weiß, was sonst), aber ist völlig dumm, was der eigentliche Workflow ist: der Server entscheidet. Um Verständnisdokumentation, Schwergewicht Lösungen arent immer erforderlich zu schaffen. Beispiele für (große) Schwergewichtswerkzeuge sind: IODocs Apigee (obwohl große Werkzeuge). Für kleine Projekte, die bereits über ein docchain-Setup verfügen (doxygenphpdocphpdoctorcustometc), benutze ich das folgende Shell-Skript, um nur die Seite in die voll-generierte Dokumentation einzubeziehen: Benutzen Sie einfach benutzerdefinierte Comment-Tags in Ihrem Quellcode. Es kann auch ein guter Ausgangspunkt für die Dokumentation aller Quellcode (Sprache) sein. Es wäre besser, die wesentlichen Teile der Antwort enthalten, und geben Sie den Link als Referenz. Ndash j0k Ihre Antwort 2017 Stack Exchange, Inc Für professionelle Marktteilnehmer Dukascopy Bank bietet die Möglichkeit der API-Integration. Die Dukascopy Bank API basiert auf dem FIX4.4 Protokoll. Die API wird verwendet, um Echtzeit-Daten-Feeds zu empfangen, Bestellungen zu übernehmen, Abbruchaufträge zu ändern und automatische Benachrichtigungen über Handelsaktivitäten zu erhalten. Mit einer FIX-API-Verbindung können die Benutzer weiterhin die Standard-Handelsplattformen der Dukascopy Bank mit ihrer grundlegenden Funktionalität nutzen. Die Positionsberechnungsmethode (netglobal position mode), die auf FIX API-Konten angewendet wird, ist jedoch unterschiedlich. LIVE-STARTANFORDERUNGEN: Die Mindestbedingungen zum Öffnen eines API-Accounts - hier klicken. Dokumentation Verbindungsschemata Die Benutzer der Dukascopy Bank FIX API haben die Wahl, über zwei verschiedene Schemata miteinander zu verbinden: Scheme 1 wird für direkte Verbindungen zu einem Dukascopy-Bankkonten verwendet, ohne Daten mit Drittanbietersoftware zu teilen. Schema 2 ermöglicht komplexere Verbindungen mit mehreren Dukascopy-Bankkonten oder die Verwendung von Drittanbieter-Datenbanken. Um mehr über FIX-API und andere handelsbezogene Informationen zu erfahren, schreiben Sie uns: infodukascopy. Rufen Sie uns an: 41 22 799 4888 oder fordern Sie einen Rückruf an.