URI-Muster für Ressourcen in RESTful-Anwendungen definieren

RESTful-Services (Representational State Transfer) basieren auf der Bearbeitung von Ressourcen. Ressourcen für RESTful-Services sind adressierbar, und URLs sind der primäre Weg, die Adressierbarkeit in REST zu realisieren.

Vorbereitende Schritte

Bestimmen Sie die Ressourcen in der Anwendung, die Sie als RESTful-Service bereitstellen möchten.

Informationen zu diesem Vorgang

URLs werden verwendet, um die Position einer Ressource anzugeben. Die Interaktion zwischen Server und Client basiert darauf, dass HTTP-Operationen an URLs abgesetzt werden. Da URLs oft eine lange Lebensdauer haben, ist es wichtig, URL-Mustern zu definieren, damit Clients direkt auf eine Ressource zugreifen können, lange, nachdem die Ressource lokalisiert wurde.

URLs werden normalerweise verwendet, wenn Sie Adressen in Web-Browser eingeben, wie z. B. http://www.ibm.com/ oder http://www.example.com/bookstore/books/ISBN123. Zwar müssen URLs von Benutzern nicht verstanden werden, doch RESTful-Services, die logische URLs in verständlichen Mustern bereitstellen, ermöglichen Entwicklern von Clientanwendungen, effizient zu arbeiten.

RESTful-Clients verwenden URLs, um Ressourcen zu bearbeiten. Jede Ressource muss ihren eigenen eindeutigen URL haben. Einige URL-Muster haben einen Sammlungspfad, dem eine eindeutige Kennung angehängt ist. Beispielsweise können Sie http://www.example.com/bookstore/books als Sammlungsressourcen-URL und http://www.example.com/bookstore/books/ISBN123 als eindeutigen Buchressourcen-URL verwenden. http://www.example.com/bookstore/books/ISBN123/authors können Sie verwenden, um eine Sammlungsressource abzurufen, die Autoren für ISBN123 beschreibt.

Der Anwendungsentwickler muss die Granularität von URLs genau berücksichtigen, da dies die Anwendungsnutzung und die Leistung beeinflussen kann. Beispielsweise können Sie die Informationen zum Autor eines Buchs als Teil der Buchressource angeben oder als eigenständige Ressource mit eigenem URL definieren, der in der Buchressource angegeben ist. Wenn der Autor noch andere Bücher verfasst hat, kann es sinnvoller sein, eine eigenständige Ressource für die Informationen zum Autor zu definieren und in einem Hyperlink der Buchressource auf sie zu verweisen.

Nachdem ein Anfangs-URL an einen Client gesendet wurde, können zugehörige Anforderungen durch Syntaxanalyse der aktuellen Ressource ermittelt werden. Im Beispiel mit dem Buch wird eine GET-Anforderung an http://www.example.com/bookstore/books/ abgesetzt, die eine Liste mit Buch-URLs einschließlich http://www.example.com/bookstore/books/ISBN123 abruft.

Da Systeme auf verfügbaren Ressourcen basieren, sind URLs im Allgemeinen langlebig. HTTP hat integrierte Statuscodes für Umadressierung, wie z. B. "301" (Dauerhaft entfernt) und "307" (Vorübergehend umgeleitet), daher verwenden Benutzer und Clients mit Caches zuvor ermittelte URLs zuerst. Sie können außerdem in Erwägung ziehen, eine Versions-ID in das URL-Muster aufzunehmen, z. B. http://www.example.com/bookstore/v2/books/ISBN123. Die Planung umfasst die Definition einer Schnittstelle mit Java™-Code. Daher sollten Sie Ihre URL-Muster aufgrund der zu erwartenden Langlebigkeit sorgfältig auswählen.

In JAX-RS (Java API for RESTful Web Services) müssen Sie @Path-Annotationen zu den Java-Klassendateien oder den Java-Methoden hinzufügen, um den relativen URL der Ressource zu definieren. Sie können JAX-RS-Unterressourcen-Locator und Unterressourcenmethoden verwenden, um Ressourcen zu definieren. Verwenden Sie Parameter, z. B. Pfadparameter oder Matrixparameter, im URL, um die Ressource zu identifizieren.

Der Wert in der @Path-Annotation definiert den relativen Teil des vollständigen URL für Ihre Ressource. Der Basis-URL wird von der Domäne, dem Port, dem Kontextstammverzeichnis des Anwendungsmoduls und allen Zuordnungen von URL-Mustern in der Datei "web.xml" für das Anwendungsmodul abgeleitet. Wenn die Domäne beispielsweise www.example.com ist, ist der Port 9060, das Kontextstammverzeichnis example, das URL-Muster des Servlets store/* und der Wert der @Path-Annotation /bookstore/books. Der vollständige URL lautet wie folgt: http://www.example.com:9060/example/store/bookstore/books.

Vorgehensweise

  1. Geben Sie die Ressourcentypen in der Anwendung an. Nehmen Sie an, Sie haben zwei Ressourcentypen, ein BooksCollection-Objekt und ein einzelnes Book-Objekt mit den folgenden Klassendefinitionen:
    public class BooksCollection {
            public BooksCollection() {
                    /* kein Argumentkonstruktor */
        }
    
    }
    
    public class Book {
            public Book(String ISBN) {
                    /* Dieser Konstruktor hat ein Argument, das mit einer JAX-RS-Annotation versehen wird.          Informationen zu gültigen Konstruktoren finden Sie in der JAX-RS-Spezifikation.
    */
        }
    }
    Laut Definition in der JAX-RS-Spezifikation werden Ressourceninstanzen per Anforderung erstellt. Damit die JAX-RS-Laufzeitumgebung eine Ressourceninstanz erstellen kann, benötigen Sie entweder einen Konstruktor ohne Argument oder einen Konstruktor, der nur annotierte JAX-RS-Parameter enthält.
  2. Fügen Sie eine Annotation "javax.ws.rs.Path" zu jeder Ressourcenklasse hinzu.  Definieren Sie den Wert für jede Annotation "@javax.ws.rs.Path" als Bestandteil des URL nach dem Basis-URL der Anwendung.
    /*
     * BooksCollection.java
      * Diese Java-Klasse repräsentiert den URL der Buchsammlung (Books Collection) unter "/bookstore/books".
     */
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
    
    }
    Nachdem Sie die Anwendung fertiggestellt haben, können Sie die Ressource über den URL http://<Hostname>:<Port>/<Kontextstammverzeichnis>/<Servletpfad>/bookstore/books aufrufen. Geben Sie für diesen URL das Kontextstammverzeichnis als Teil des URL nach dem Kontextmodul an. Geben Sie den Servletpfad und alle URL-Pfade in der Datei "web.xml" an, falls vorhanden.
  3. Optional: Stellen Sie fest, ob eine Ressource einen Teil des URL als Parameter verwenden muss. Wenn eine Ressource einen Teil des URL als Parameter verwenden muss, z. B. als Kennung, können Sie die Annotation @javax.ws.rs.Path mit einem regulären Ausdruck verwenden. Sie können dann die Annotation "@javax.ws.rs.PathParam" im Ressourcenkonstruktor oder in der Ressourcenmethode hinzufügen.
    /*
      * "Book.java repräsentiert einzelne Bücher.
      */
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
       public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
    
       }
    }
    Wenn eine HTTP-Anforderung für die URL http://<Hostname>:<Port>/<Kontextstammverzeichnis>/<Servletpfad>/bookstore/books/ISBN-Nummer abgesetzt wird, wird eine Buchinstanz mit ISBN-Nummer an den Parameter ISBN des Konstruktors übergeben.

    Näheres zu weiteren gültigen Parametern finden Sie in den Informationen zur Definition von Parametern für Anforderungen, die sich auf Ressourcen in RESTful-Anwendungen beziehen.

  4. Erstellen Sie die Unterklasse "javax.ws.rs.core.Application", um für die JAX-RS-Laufzeitumgebung zu definieren, welche Klassen Bestandteile der JAX-RS-Anwendung sind. Die Ressourcenklassen werden in der Methode getClasses() zurückgegeben. Beispiel:
    public class BookApplication extends javax.ws.rs.core.Application {
        public Set<Class<?>> getClasses() {
            Set<Class<?>> classes = new HashSet<Class<?>>();
            classes.add(BooksCollection.class);
            classes.add(Book.class);
            return classes;
        }
    }

    Wenn Sie die Unterklasse "javax.ws.rs.core.Application" definieren, werden die von ihren Methoden zurückgegebenen Klassen in der JAX-RS-Laufzeitumgebung zurückgegeben. Wenn Sie die Datei "web.xml" konfigurieren, müssen Sie die Unterklasse "javax.ws.rs.core.Application" als Parameter für das Servlet oder den Filter angeben. Näheres finden Sie in den Informationen zur Konfiguration der Datei "web.xml" für JAX-RS-Anwendungen.

Ergebnisse

Sie haben einen URL erstellt, um Ihre Ressourcen für Ihren RESTful-Service anzugeben. Wenn Sie in einem frühen Entwurfsstadium Problemstellungen im Zusammenhang mit URL-Mustern berücksichtigen, verbessern Sie damit die Benutzerfreundlichkeit des RESTful-Service und erhöhen langfristig seinen Nutzen.

Nächste Schritte

Die vom definierten URL angegebene Ressource existiert. Die Ressource hat jedoch keine Methoden, mit denen Aktionen für HTTP-Methoden, wie z. B. GET, POST, PUT oder DELETE, ausgeführt werden können. Näheres zur Definition von Ressourcenfunktionen mit unterstützten HTTP-Methoden finden Sie in dem Artikel, der sich mit der Definition von Ressourcenmethoden für RESTful-Anwendungen befasst.


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_uri
Dateiname:twbs_jaxrs_defresource_uri.html