Dokumentation einer REST-Schnittstelle mit einem Flussdiagramm

9

Hat jemand Vorschläge zum Erstellen einer Flussdiagrammdarstellung einer REST-artigen Weboberfläche? Um den Mitentwicklern eine gründliche Dokumentation zur Verfügung zu stellen, habe ich mich mit der Modellierung der Schnittstelle zum Ändern und Generieren einer Produktressource beschäftigt:

Geben Sie hier die Bildbeschreibung ein

Dieses spezielle System verhält sich bei der Benutzerauthentifizierung / Ressourcenanzahl anders. Bevor ich Änderungen vornehme, suche ich nach einer Klarstellung:

  • Komplexität: Wie würden Sie die Gesamtstruktur vereinfachen, um die Lesbarkeit zu verbessern?
  • Anzeigesymbol: Ist dies für die Darstellung einer Seite geeignet?
  • Symbol für manuelle Bedienung: Ist dies geeignet, um eine Benutzeraktion wie einen Klick auf eine Schaltfläche darzustellen?

Alle anderen Vorschläge wäre sehr dankbar.

Ich entschuldige mich für die erneute Veröffentlichung. Die Haupt-Stackexchange-Site schlug vor, diese Frage besser für Programmierer zu stellen.

documentation rest flowchart James Kassemi
quelle

Antworten:

12

Ich bin der Meinung, dass Message Sequence Chart / Sequence Diagram besser zur Dokumentation der RESTful API-Interaktion geeignet ist. Was Sie haben, ist ein Zustandsdiagramm, während die RESTful-API per Definition zustandslos ist.

Geben Sie hier die Bildbeschreibung ein

vartec
quelle
5
Der Server in einer RESTful-Architektur ist zustandslos, das System selbst jedoch nicht. Der Status wird auf dem Client gespeichert, und mögliche Statusübergänge werden in der Darstellung einer Ressource codiert, sodass der Client den Übergang in einen neuen Status initiieren kann, indem er eine Anforderung an den Server sendet. Ich denke, ein Zustandsdiagramm ist sehr effektiv bei der Kommunikation des Gesamtsystemstatus, auch wenn es die Anforderungen und Antworten zwischen den Client- und Serverkomponenten nicht genau dokumentiert.
Adam Jaskiewicz
1
@Adam: Sie haben Recht mit dem Gesamtsystem. Bei der Frage geht es jedoch explizit um die Dokumentation der REST-Schnittstelle, nicht des gesamten Systems.
Vartec
Dank vartec dokumentiert die MSC die REST-Schnittstelle in diesem Fall effektiv. Ich bin immer noch gespannt auf Verbesserungen an der Dokumentation des Kundenstatus dieses Modells.
James Kassemi
1
RESTful-Systeme, die die Hypertext-Einschränkung implementieren, bewirken, dass der Client als Zustandsmaschine fungiert. Ich habe festgestellt, dass die Verwendung von Zustandsmaschinentypdiagrammen ein weitaus effektiveres Werkzeug zur Dokumentation von RESTful-Client / Server-Interaktionen ist.
Darrel Miller
Kann man if-s und while-s in diesem Diagramm beschreiben?
Hellboy
1

Ich denke definitiv, dass eine Zustandsmaschine der richtige Weg ist, um die Interaktionen eines RESTful-Systems zu dokumentieren. Ich arbeite jedoch immer noch an der richtigen Darstellung der Hypermedia-Faktoren im Diagramm. Hier sind einige experimentelle Diagramme, die ich gemacht habe.

Matze

Geben Sie hier die Bildbeschreibung ein

Darrel Miller
quelle
0

Meine zwei Pennies zu diesem Thema, während ich gerade damit arbeite:

  • Fokus auf Ressourcen und ihre Beziehungen
    • und nicht auf die Aktion und damit die HTTP-Methode
    • Wenn Sie einem Link folgen, unabhängig davon, ob Sie einen GET oder POST durchgeführt haben, werden Ihre nächsten möglichen Zustände hauptsächlich von der aktuellen Ressource und viel weniger von der HTTP-Methode der Anforderung bestimmt

In diesem Sinne:

  • Entfernen Sie einige offensichtliche Links (dh zu sich selbst, zu root)
  • Entfernen Sie die Bezeichnung der Relationen, wenn nur "dieses [Auto] hat einen [Eigentümer]" angegeben ist, wobei die Quellressource Auto und die Zielressource Eigentümer ist. Es fügt nichts hinzu
  • Ein interaktives Diagramm kann bei einem komplexen Zustandsdiagramm ( Beispiel ) eine große Hilfe sein.
Andrei Neculau
quelle