Es ist verständlich, ein wenig verwirrt darüber zu sein, wie REST richtig eingesetzt wird, basierend auf all den Möglichkeiten, wie ich große Unternehmen beim Entwurf ihrer REST-APIs gesehen habe.
Sie haben Recht, dass REST ein Ressourcensammelsystem ist. Es steht für Representational State Transfer. Keine gute Definition, wenn Sie mich fragen. Die Hauptkonzepte sind jedoch die 4 HTTP-VERBs, die zustandslos sind.
Das Wichtige ist, dass Sie nur 4 VERBS mit REST haben. Dies sind GET, POST, PUT und DELETE. Ihr resendBeispiel wäre das Hinzufügen eines neuen Verbs zu REST. Dies sollte eine rote Fahne sein.
Frage 1
Es ist wichtig zu wissen, dass der Aufrufer Ihrer REST-API nicht wissen muss, dass das Ausführen einer PUTfür Ihre Sammlung dazu führen würde, dass eine E-Mail generiert wird. Das riecht nach einem Leck für mich. Was sie wissen könnten, ist, dass das Ausführen von a PUTzu zusätzlichen Aufgaben führen könnte, die sie später abfragen könnten. Sie würden dies wissen, indem sie eine GETfür die kürzlich erstellte Ressource ausführen . Das GETzurückkehren würde die Ressource und alle der TaskRessource - ID ist mit ihm verbunden. Sie können diese Aufgaben später abfragen, um ihren Status zu ermitteln und sogar eine neue Aufgabe einzureichen Task.
Sie haben einige Möglichkeiten.
REST - Aufgabenressourcenbasierter Ansatz
Erstellen Sie eine tasksRessource, in der Sie bestimmte Aufgaben an Ihr System senden können, um Aktionen auszuführen. Sie können dann GETdie Aufgabe basierend auf der IDzurückgegebenen Aufgabe bestimmen, um ihren Status zu bestimmen.
Sie können auch einen SOAP over HTTPWebdienst einmischen, um Ihrer Architektur RPC hinzuzufügen.
Abfrage aller Aufgaben für eine bestimmte Ressource
GET http://server/api/myCollection/123/tasks
{ "tasks" :
[ { "22333" : "http://server/api/tasks/223333" } ]
}
Beispiel für eine Aufgabenressource
PUT http://server/api/tasks
{
"type" : "send-email" ,
"parameters" :
{
"collection-type" : "foo" ,
"collection-id" : "123"
}
}
==> gibt die ID der Aufgabe zurück
223334
GET http://server/api/tasks/223334
{
"status" : "complete" ,
"date" : "whenever"
}
REST - Verwenden von POST zum Auslösen von Aktionen
Sie können POSTeiner Ressource jederzeit zusätzliche Daten hinzufügen. Meiner Meinung nach würde dies den Geist von REST verletzen, aber es wäre immer noch konform.
Sie können einen ähnlichen POST durchführen:
POST http://server/api/collection/123
{ "action" : "send-email" }
Sie aktualisieren die Ressource 123 aus der Sammlung mit zusätzlichen Daten. Diese zusätzlichen Daten sind im Wesentlichen eine Aktion, die das Backend anweist, eine E-Mail für diese Ressource zu senden.
Das Problem, das ich dabei habe, ist, dass ein GETauf der Ressource diese aktualisierten Daten zurückgibt. Dies würde jedoch Ihre Anforderungen lösen und dennoch RESTful sein.
SOAP - Webdienst, der von REST erhaltene Ressourcen akzeptiert
Erstellen Sie einen neuen WebService, in dem Sie E-Mails basierend auf der vorherigen Ressourcen-ID über die REST-API senden können. Ich werde hier nicht näher auf SOAP eingehen, da es sich bei der ursprünglichen Frage um REST handelt und diese beiden Konzepte / Technologien nicht verglichen werden sollten, da es sich um Äpfel und Orangen handelt .
Frage 2
Sie haben hier auch einige Optionen:
Es scheint, dass viele größere Unternehmen, die REST-APIs veröffentlichen, eine searchSammlung verfügbar machen , die eigentlich nur eine Möglichkeit ist, Abfrageparameter zu übergeben, um Ressourcen zurückzugeben.
GET http://server/api/search?q="type = myCollection & someField >= someval"
Was eine Sammlung voll qualifizierter REST-Ressourcen zurückgeben würde, wie z.
{
"results" :
{ [
"location" : "http://server/api/myCollection/1",
"location" : "http://server/api/myCollection/9",
"location" : "http://server/api/myCollection/56"
]
}
}
Oder Sie können MVEL als Abfrageparameter zulassen .
Frage 3
Ich bevorzuge die Unterebenen, als die andere Ressource mit einem Abfrageparameter abfragen zu müssen. Ich glaube nicht, dass es auf die eine oder andere Weise eine Regel gibt. Sie können beide Möglichkeiten implementieren und dem Anrufer ermöglichen, anhand der ersten Eingabe in das System zu entscheiden, welche Option besser geeignet ist.
Anmerkungen
Ich bin nicht einverstanden mit den Lesbarkeitskommentaren anderer. Ungeachtet dessen, was manche vielleicht denken, ist REST immer noch nicht für den menschlichen Verzehr bestimmt. Es ist für den Maschinenverbrauch. Wenn ich meine Tweets sehen möchte, benutze ich die reguläre Twitters-Website. Ich führe kein REST GET mit ihrer API durch. Wenn ich programmgesteuert etwas mit meinen Tweets machen möchte, verwende ich deren REST-API. Ja, APIs sollten verständlich sein, aber Ihre gtesind nicht so schlecht, sie sind einfach nicht intuitiv.
Die andere Hauptsache bei REST ist, dass Sie an jedem beliebigen Punkt in Ihrer API beginnen und zu allen anderen zugeordneten Ressourcen navigieren können sollten, ohne die genaue URL der anderen Ressourcen im Voraus zu kennen. Die Ergebnisse des GETVERB in REST sollten die vollständige REST-URL der Ressourcen zurückgeben, auf die verwiesen wird. Anstelle einer Abfrage, die die ID eines PersonObjekts zurückgibt, wird die vollständig qualifizierte URL zurückgegeben, z http://server/api/people/13. Dann können Sie jederzeit programmgesteuert durch die Ergebnisse navigieren, auch wenn sich die URL geändert hat.
Antwort auf Kommentar
In der realen Welt müssen tatsächlich Dinge geschehen, die keine Ressource erstellen, lesen, aktualisieren oder löschen (CRUD).
Zusätzliche Maßnahmen können für Ressourcen ergriffen werden. Typische relationale Datenbanken unterstützen das Konzept der gespeicherten Prozeduren. Dies sind zusätzliche Befehle, die für einen Datensatz ausgeführt werden können. REST hat dieses Konzept nicht von Natur aus. Und es gibt keinen Grund dafür. Diese Arten von Aktionen eignen sich perfekt für RPC- oder SOAP-Webdienste.
Dies ist das allgemeine Problem, das ich bei REST-APIs sehe. Entwickler mögen die konzeptionellen Einschränkungen, die REST umgeben, nicht, deshalb passen sie es an, um zu tun, was sie wollen. Das macht es jedoch zu einem RESTful-Service. Im Wesentlichen werden diese URLs zu GETAufrufen von Pseudo-REST-ähnlichen Servlets.
Sie haben einige Möglichkeiten:
- Erstellen Sie eine Aufgabenressource
- Unterstützung
POSTzusätzlicher Daten zur Ressource, um eine Aktion auszuführen.
- Fügen Sie die zusätzlichen Befehle über einen SOAP-Webdienst hinzu.
Wenn Sie einen Abfrageparameter verwenden würden, welches HTTP-VERB würden Sie zum erneuten Senden der E-Mail verwenden?
GET- Sendet dies die E-Mail erneut UND gibt die Daten der Ressource zurück? Was ist, wenn ein System diese URL zwischengespeichert und wie die eindeutige URL für diese Ressource behandelt hat? Jedes Mal, wenn sie auf die URL klicken, wird eine E-Mail erneut gesendet.POST - Sie haben keine neuen Daten an die Ressource gesendet, sondern nur einen zusätzlichen Abfrageparameter.
Basierend auf allen gegebenen Anforderungen wird das Problem gelöst, wenn Sie eine POSTRessource mit action fieldPOST-Daten bearbeiten.