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.

Das folgende Beispiel veranschaulicht die Beispieldatei web.xml:
<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

  1. Geben Sie die Ressourcentypen in der Anwendung an.
    Geben Sie für jede Ressourcenklasse eine vorhandene Methode an, oder erstellen Sie eine Methode, die Sie für jede unterstützte HTTP-Methode aufrufen möchten. Methoden, die auf HTTP-Anforderungen antworten, werden auch als Ressourcenmethoden bezeichnet. Versehen Sie bei jeder Ressourcenmethode in der Ressourcenklasse die Java™-Methode mit einer einzelnen JAX-RS-Annotation für HTTP-Methoden. Beispiele: @javax.ws.rs.GET, @javax.ws.rs.POST, @javax.ws.rs.DELETE, @javax.ws.rs.PUT. Wenn eine HTTP-GET-Methode von der Klasse "BooksCollection" unterstützt wird, können Sie eine Methode wie im folgenden Codeausschnitt erstellen und annotieren:
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
        @javax.ws.rs.GET
        public String getBooksCollection() {
                    String str = /* Erstellen Sie eine Zeichenfolgedarstellung (String) für die Ressource.*/
            return str;
        }
    }
    Wenn eine HTTP-GET-Anforderung für die URL http://<Hostname>:<Port>/<Kontextstammverzeichnis>/<Servletpfad>/bookstore/books aus einem Web-Browser oder einem anderen HTTP-Client abgesetzt wird, wird die vorherige Methode getBooksCollection() aufgerufen.
  2. Vergewissern Sie sich, dass die Ressource die erforderlichen HTTP-Methoden unterstützt.
    Jeder Ressource hat normalerweise mehrere Ressourcenmethoden, wie z. B. folgende:
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
            /* Dies ist ein Datenbankschlüssel. */
            private String ISBN;
    
        public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
                    this.ISBN = ISBN;
        }
    
        @javax.ws.rs.GET
        public String retrieveSpecificBookInformation() {
                    /* Dieser Code ruft Buchressourcen auf der Basis der ISBN-Nummer ab. */
        }
    
        @javax.ws.rs.PUT
            public String updateBookInformation(String updatedBookInfo) {
                    /* Dieser Code aktualisiert Buchressourcen auf der Basis der ISBN-Nummer und der Entität (Nachrichtentext), die in der in "updatedBookInfo" gespeicherten Anforderung gesendet wird. */
        }
    
        @javax.ws.rs.DELETE
        public void removeBook() {
                    /* Dieser Code löscht Buchressourcen auf der Basis der ISBN-Nummer. */
        }
    }
    Wenn eine HTTP-GET-Anforderung für die URL http://<Hostname>:<Port>/<Kontextstammverzeichnis>/<Servletpfad>/bookstore/books/<ISBN-Nummer> aus einem Web-Browser oder einem anderen HTTP-Client abgesetzt wird, wird die Methode retrieveSpecificBookInformation() aufgerufen. Wenn eine HTTP-PUT-Anforderung an einen URL gesendet wird, wird die Methode "updateBookInformation" aufgerufen, und jeder Inhalt im Anforderungsnachrichtentext wird als Wert des Objekts updatedBookInfo übergeben. Wenn eine HTTP-DELETE-Anforderung an einen URL gesendet wird, wird die Methode removeBook() aufgerufen.
    Fehler vermeiden Fehler vermeiden: Gemäß der JAX-RS-Spezifikation dürfen Sie nicht mehrere HTTP-Methodenannotationen wie "@javax.ws.rs.POST" oder "@javax.ws.rs.PUT" in dieselbe Ressourcenmethode aufnehmen. Da HTTP-Methoden eine definierte Semantik haben, darf eine Ressourcenmethode nicht für mehrere HTTP-Methoden verwendet werden. gotcha

Ergebnisse

Sie haben gültige Operationen für die Ressourcen definiert.


Symbol, das den Typ des Artikels anzeigt. Taskartikel



Symbol für Zeitmarke Letzte Aktualisierung: 25.05.2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_httpmeth
Dateiname:twbs_jaxrs_defresource_httpmeth.html