Eine gute ReST-Dokumentation würde bedeuten, dass Sie Ihren Medientyp und nur Ihren Medientyp dokumentieren.
In einem typischen Szenario würden Sie ein Dokument wie folgt erstellen:
Die Acme Corp XML-Formate
Linkerkennung
Links zu verschiedenen Ressourcen werden in einem Dokument beschrieben, das gefunden werden kann, indem eine GET- oder HEAD-Anforderung an den Server über einen Lesezeichen-URI (normalerweise das Stammverzeichnis des Servers, http://www.acme.org ) gesendet und nach einem gesucht wird HTTP Link Header:
Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml
Dabei ist der relTeil die Verknüpfungsbeziehung und xxxder URI, für den die Beziehung hergestellt wurde.
Beziehungen verknüpfen
Dieses Dokument definiert die folgenden Beziehungsnamen:
Medientypen
Dies application/vnd.acme.services+xmlist ein Dokument mit einer xmlSerialisierung, das eine Liste von Links beschreibt, die eine Anwendung möglicherweise verarbeiten möchte.
<links>
<link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>
Das applcation/vnd.acme.customers+xml ist ein Dokument mit einer xmlSerialisierung, die Kunden beschreibt.
Beispieldokumente:
<customers>
<customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>
usw...
Der Punkt ist, dem Entwickler eine Möglichkeit zu geben, den von Ihnen definierten Links zu folgen. Suchen Sie zuerst den Link zum Index damit sie die Liste der Dinge erhalten, zu denen sie navigieren können.
Sobald sie dieses Dokument entdeckt haben, stellen sie fest, dass sie eine Liste von Kunden bei einem bestimmten Uri sehen und eine ausführen können GET können.
Wenn sie einen Kunden von Interesse finden, können sie dem in definierten Link folgen /customers/customer/@hrefund a ausgebenGET , um eine Darstellung dieses Kunden abzurufen.
Von dort aus kann Ihr Medientyp Aktionen einbetten, die dem Benutzer mithilfe weiterer Links zur Verfügung stehen. Sie haben auch die zusätzliche Möglichkeit, eine OPTIONS-Anforderung für die Ressource auszugeben, um festzustellen, ob Sie das Löschen der Ressource zulassen können, oder einen PUT, wenn Sie das Dokument nach der Änderung wieder speichern können.
Eine gute Dokumentation gibt es also nie:
- Geben Sie statische Links
- Geben Sie eine Interaktion wie "Sie können mit diesem Medientyp einen POST für den Kunden ausstellen, und das bedeutet den Verschiebungsvorgang". Der Client sollte einen POST nur gegen den Kunden ausstellen, weil Ihr XML-Dokument dies so angegeben hat.
Bei alledem geht es darum, eine minimale Kopplung zwischen Clients und Servern zu erreichen. Der Client kann sehr intelligent Ressourcen anzeigen und entdecken (Formulare anzeigen und Gott weiß was noch), ist aber völlig dumm, was der eigentliche Workflow ist: Der Server entscheidet.