heikomaass

Was zeichnet eigentlich einen guten Webservice aus ? Hier eine Liste von Anforderungen, die ein guter Webservice erfüllen muss.

1. Versioniert
Webservices ändern sich. Im Idealfall kommen nur neue, optionale Attribute hinzu, ohne dass ältere Clients kaputt gehen. Bei umfangreicheren Umstrukturierungen ist dies aber nicht der Fall: Die neue Version ist nicht mehr rückwertskompatibel. Hier muss sowohl die alte und die neue Version des Webservice eine Zeit lang parallel betrieben werden. Von daher muss die Version in die URL des Webservice mit aufgenommen werden (z.B. http://api.stackexchange.com/2.0/tags?order=desc&sort=popular&site=stackoverflow).

2. Zustandslos
Ein Webservice darf keine Session-Ids oder gar Cookies einsetzen. Lesende Requests sollten unabhängig von einander ausgeführt werden können; eine bestimmte Reihenfolge darf nicht vorgegeben sein.

3. Verständlich auch ohne Dokumentation
Methodennamen und Parameter sollten nicht kryptisch sein. Beispiel: Die Bedeutung von totalHits ist verständlicher als die von th. Zwar werden bei der kürzeren Variante ein paar Bytes eingespart, aber auf Kosten der Verständlichkeit. Wie Bytes besser eingespart werden, zeigt der nächste Punkt.

4. Kompakt
Der Webserver sollte die GZIP-Komprimierung anbieten. Des weiteren sollte der Webservice auch JSON zurückgeben, um das Parsen für die Clients zu erleichtern und die Datenmenge zusätzlich zu reduzieren.

5. Im Browser testbar
Jeder Webservice muss eine Testseite zur Verfügung stellen, auf der alle Requests und Parameter ausprobiert werden können. Beispiele dafür:

• https://api.stackexchange.com/docs
• http://www.flickr.com/services/api/explore/flickr.galleries.getPhotos

Testseiten erleichtern das Erlernen des Webservices und ermöglichen den schnellen Test unabhängig von irgendwelchen Tools. Gute Testseiten können sogar eine separate Dokumentation ersetzen.

6. Auskunftsfreudig bei Fehlern
Es ist ziemlich frustrierend, wenn der Webservice bei syntaktisch falschen oder fehlenden Parametern einfach nur eine Standardfehlermeldung zurückgibt. Wichtig ist, dass der Webservice mitteilt, was genau schief gelaufen ist. Beispiel:

{
  "error" : {
    "name" : "missing_parameter",
    "description" : "parameter 'lang' is missing"
  }
}

Des Weiteren muss der Server bei einem Fehlerfall auch den HTTP-Code korrekt setzen. Bei clientseitigen Fehlern sollte der Server einen HTTP 400 (Bad Request) schicken, bei serverseitigen Fehlern dagegen einen HTTP 500 (Internal Server Error). Dies erleichtert das Cachingverhalten und die Fehlerbehandlung auf Seiten des Clients.

7. Konsistent
Parameternamen sollten über alle Methoden hinweg identisch benannt werden. Ansonsten muss der Client diese Inkonsistenzen abfangen, was die Client-Implementierung wieder aufwändiger macht.

Wie ich diese Woche feststellen durfte, implementiert der IBM Websphere 6.x (und sogar der Websphere 7.x) die Servlet Specification nicht richtig. Konkret geht es um das Verhalten von getServletPath() und getPathInfo() des HttpServletRequests.

Wie es sein muss:

Angenommen, wir haben eine Webapp unter dem Context mystore und mappen genau ein Servlet auf den Defaultpath “/”. Wenn wir folgende URL aufrufen: /mystore/search/de, dann sehen wir im Apache Tomcat folgendes:

getServletPath(): "/search/de"
getPathInfo(): null""
Editiert am 1.4.2012: Der Tomcat liefert einen leereren String, anstelle von null zurück.

Dieses Verhalten wird in der Servlet Api 2.4 unter dem Kapitel “Specification of Mappings” festgelegt:

A string containing only the ’/’ character indicates the “default” servlet of the application. In this case the servlet path is the request URI minus the context path and the path info is null.

Wie es der Websphere macht:

Der Websphere behandelt das Default-Mapping genauso wie ein Directory-Mapping also “/*”. Somit gibt er folgendes zurück:

getServletPath(): ""
getPathInfo(): "/search/de"

Das ist natürlich unglücklich, da man im Code nun eine Fallunterscheidung machen muss.

Spring hilft:

Die Methode getPathWithinServletMapping aus der UrlPathHelper-Klasse des Spring Frameworks schafft hier Abhilfe. Wenn getServletPath() null ist, liefert die Methode stattdessen die Antwort von getPathInfo() zurück. Wichtig: Dies funktioniert aber erst seit dem Spring Release 3.0.3.
Editiert am 1.4.2012: getPathWithinServletMapping() gibt natürlich nicht den ServletPath zurück, sondern nur die Pfadangabe hinter dem ServletPath. Von daher ist dies nicht die korrekte Lösung. Nachfolgend stelle ich stattdessen die Methode getPathWithinApplication vor, die mir in meinem Anwendungsfall die Fallunterscheidung zwischen Websphere und Tomcat erspart hat:

Die Methode getPathWithinApplication aus der UrlPathHelper-Klasse des Spring Frameworks liefert den restlichten Pfad nach dem Context, unabhängig ob er vom ServletPath oder PathInfo kommt.

Weitere Lektüre:

http://www-01.ibm.com/support/docview.wss?uid=swg1PK39337
https://issues.apache.org/jira/browse/TAPESTRY-1713