Ressourcenmethoden für RESTful-Anwendungen definieren
Einzelne Ressourcen können ihre Funktion mit unterstützten HTTP-Methoden definieren. In REST-Services (Representational State Transfer) sind die unterstützten Methoden GET, PUT, DELETE, POST. Alle Operationen werden normalerweise ausgeführt, wenn eine der vordefinierten HTTP-Methoden mit einer Ressource verwendet wird.
Vorbereitende Schritte
Machen Sie sich mit den vordefinierten HTTP-Methoden und deren bekannten Attributen vertraut. Einige HTTP-Methoden gelten als sicher in dem Sinne, dass das Absetzen der Anforderung die Ressource nicht ändert, bzw. als idempotent, d. h., dass mehrfache Aufrufe der Operation das Ergebnis nicht ändern. HTTP-Methoden sind zwar für bestimmte Attribute definiert, die Serviceimplementierung folgt jedoch den Definitionen. Die Beschreibung der HTTP-Methodendefinitionen enthält weitere Informationen zu den allgemeinen Methodengruppen für HTTP.
Informationen zu diesem Vorgang
Clients verwenden HTTP-Methoden, um bestimmte Operationen ausführen zu können. Im Gegensatz zu anderen verteilten Systemen, in denen jedes einzelne System eindeutige Schnittstellen definiert, stützen sich RESTful-Systeme, die auf HTTP basieren, auf vordefinierte Methoden. Die vier gebräuchlichsten Methoden sind GET, PUT, DELETE, POST. Ressourcen müssen nicht zwangsläufig alle HTTP-Methoden für alle Clients zulassen.
Die HTTP-Methode GET ruft eine Ressourcendarstellung ab. Sie ist sicher und idempotent. Wiederholte GET-Anforderungen führen keine Änderung von Ressourcen herbei.
Die HTTP-Methode PUT wird oft verwendet, um Ressourcen zu aktualisieren oder eine neue Entität unter einem bekannte URL anzugeben. Muss eine Ressource aktualisiert oder erstellt werden, wird eine HTTP-PUT-Methode mit den neuen Ressourcendaten als Anforderungsentität (Nachrichtentext) an den Ressourcen-URL abgesetzt. Die HTTP-Methode PUT ist idempotent. Somit liefern identische PUT-Anforderungen mit derselben Entität, die an denselben URL abgesetzt werden, dasselbe Ergebnis wie eine einzige PUT-Anforderung. Diese Methode setzt voraus, dass keine anderen relevanten Anforderungen abgesetzt wurden.
Die HTTP-Methode DELETE entfernt eine Ressource an einer bestimmten URL.
Die HTTP-Methode POST wird oft verwendet, wenn Sie eine Ressource in einer Sammlung erstellen und der endgültige Ressourcen-URL nicht bekannt ist. Nehmen Sie beispielsweise an, ein Administrator setzt eine POST-Anforderung an die Sammlungsressource /users ab, die einen Benutzer mit einer eindeutigen ID wie 1234567890 erstellt. Die eindeutige ID wird dann als Teil des URL-Pfads verwendet, um die neue Benutzerressource, z. B. /users/1234567790, zu beschreiben. Sie ist nicht sicher und nicht idempotent. In diesem Fall kann bei mehreren POST-Anforderungen, die an die Sammlung /users abgesetzt werden, immer wieder eine neue eindeutige ID erstellt und zur Benutzersammlung hinzugefügt werden, auch wenn der Benutzer dieselben Informationen hat.
Da die meisten RESTful-Services anerkannte HTTP-Methoden verwenden, die erwartete Ergebnisse bereitstellen, können Sie Clients einfacher erstellen. Entwickler von RESTful-Services können vom erwarteten Verhalten von HTTP-Methoden profitieren. Ressourcenmethoden können ebenfalls Parameter, z. B. Pfadparameter, Abfrageparameter oder Matrixparameter verwenden, um die Ressource zu identifizieren. Nähere Details hierzu finden Sie in den Artikeln, die sich mit der Nutzung von Parametern für Anforderungsdarstellungen in Ressourcen befassen.
(Optional) Wenn eine Unterresourcenmethode und eine Unterressourcen-Locator-Methode existieren, die eine Annotation vom Typ @Path mit demselben Wert in derselben Ressourcenklasse haben, wird der Unterresourcen-Locator nicht berücksichtigt, wenn die Methode bestimmt wird, die standardmäßig aufgerufen werden soll. Das entspricht den Bestimmungen der JAX-RS-Spezifikation.
Um dieses Verhalten zu ändern, müssen Sie die Eigenschaft wink.searchPolicyContinuedSearch mit dem Wert true verwenden. Dies bewirkt, dass Unterressourcen-Locator verwendet werden, wenn keine Unterressourcenmethoden der Anforderung entsprechen.
Um die Eigenschaft zu aktivieren, müssen Sie eine Eigenschaftendatei in das Verzeichnis WEB-INF des Moduls aufnehmen, für das die Eigenschaft wink.searchPolicyContinuedSearch mit dem entsprechenden Wert angegeben ist. Fügen Sie in der Datei web.xml des Anwendungsmoduls ein Element vom Typ init-param mit dem Wert propertiesLocation für das Element param-name ein. Das Element param-value gibt die Position der Eigenschaftendatei, z. B. WEB-INF/my_wink.properties, an.
<servlet>
...
...
<init-param>
<param-name>propertiesLocation</param-name>
<param-value>/WEB-INF/my_wink.properties</param-value>
</init-param>
</servlet>
Das folgende Beispiel veranschaulicht die Eigenschaftendatei WEB-INF/my_wink.properties:
wink.searchPolicyContinuedSearch=true
Im folgenden Codebeispiel endet die Anforderungs-URL mit sayhello. Die Anforderung enthält jedoch eine POST- anstelle einer GET-Methode, daher wird die Nachricht "HTTP 405 Method Not Allowed error" (Methode nicht zulässig) zurückgegeben. Um diesen 405-Fehler zu vermeiden, stellen Sie sicher, dass die gesendete HTTP-Methode mit der Methodenannotation übereinstimmt.
@javax.ws.rs.Path("helloworld")
public class SampleResource {
...
@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...
Vorgehensweise
Ergebnisse
Sie haben gültige Operationen für die Ressourcen definiert.