Erste Schritte mit der Rest API von Lotus Domino

Im letzten Post habe ich gezeigt, wie einfach es ist die REST Api für einen Domino Server zu aktivieren. Jetzt möchte ich zeigen wie man die API ohne ein Programm zu schreiben testen kann und erste Erfahrungen mit der Syntax der RESTurls gewinnen kann.

Dafür erscheint mir die RESTClient Extension für den Firefox am besten geeignet. Diese Extension kann auf Knopfdruck zum Firefox hinzugefügt. werden.

Nach einem Neustart des Firefox ist der RESTClient im Browser verfügbar. Der Knopf für den RestClient befindet sich ganz rechts in der Adresszeile.

In der UI des RESTClient kann man dann seine Zugriffsmethode, die URL und bei Bedarf auch Daten im Body mitschicken.

Wie sehen nun aber die URLs für den Zugriff auf Domino Daten aus. Hier ein paar Beispiele:

Erstellen einer Liste sämtlicher Datenbanken auf dem Domino Server:

http://localhost:80/api/data

Zugriff auf den Inhalt einer View:

http://localhost:80/test.nsf/api/data/collections/name/Adressen

test.nsf ist der Datenbankname und Adressen der Ansichtsname der zurückgegeben werden soll.

Zugriff auf ein Dokument mit einer bestimmten UNID:

http://localhost:80/test.nsf/api/data/documents/unid/9721E84AF9E25C4AC1257AE200598E50

Nach dem man im RESTClient dann auf den "SEND" Knopf gedrückt hat, werden einem die Ergebnisse der Abfrage unten angezeigt. Im Reiter "Response Headers" sieht man die HTTP Headers. Im Response Body sieht man das zurückgegebene JSON Dokument, dass die angeforderten Daten enthält. Hier ein kleines Notesdokument mit 2 Feldern:

{
    "@href":"http:\/\/localhost:80\/test.nsf\/api\/data\/documents\/unid\/9721E84AF9E25C4AC1257AE200598E50",
    "@unid":"9721E84AF9E25C4AC1257AE200598E50",
    "@noteid":"8F6",
    "@created":"2012-12-28T16:18:11Z",
    "@modified":"2012-12-28T16:18:27Z",
    "@authors":"CN=Ralf M Petter\/O=Demo",
    "@form":"Test",
    "Name1":"Ralf",
    "Name2":"Petter"
}

Natürlich kann das REST Api des Domino Servers noch viel mehr und jede URL bietet auch noch diverse Parameter um das Ergebnis zu beeinflussen. Einen guten Überblick über die Möglichkeiten, bekommt man in der REST Referenz im IBM Developer Wiki.

Das REST Api hat meiner Meinung nach enormes Potential für Anwendungen die nur lose an Domino angekoppelt werden sollen und der RESTClient im Firefox ist ein Super Werkzeug um seine ersten Schritte in diesem neuen Umfeld zu machen.

Aktivieren des REST Api der Domino Data Services am Server

Seit 8.5.3 Upgrade Pack 1 gibt es mit dem Domino Data Services eine neue Methode um auf die Daten eines Lotus IBM Domino Server zuzugreifen. Ein Teil dieser Domino Data Services ist ein REST Api mit dem man Daten aus Domino Datenbanken über eine einfache URL als JSON Objekte zurückbekommt. Dies sieht wirklich nach einer sehr viel versprechenden Technologie aus, da man in einem Clientprogramm egal ob es sich jetzt um einen Rich client, einen Webclient oder einen Mobilen Client keine Librarys wie notes.jar installieren muss, um auf Daten von Domino Servern zugreifen zu können.

Die Voraussetzungen für die Verwendung der Domino Data Services sind ein installiertes Upgrade Pack 1 auf 8.5.3 oder natürlich noch besser ein Domino 9 Server. Ich habe alle meine Tests mit einem 9er Server durchgeführt. Die Domino Data Services sind standardmäßig nicht aktiviert und müssen über den Admninistrator freigeschalten werden.

Konfiguration ohne Internet Site Dokument

Im Server Dokument im Tab "Internet Protocols/Domino Web Engine" befindet sich ganz unten der Punkt "Domino Access Services" Bei dem Feld "Enabled Services" muss der Punkt "Data angehakt werden. Danach muss man mit "tell nhttp quit" und "load nhttp" den Http Task von Domino durchstarten und die Data Services sollten funktionieren.

Konfiguration mit Internet Site Dokument

In dem Internet Site Dokument befindet sich die Einstellung für die Domino Data Services auf dem Tab "Configuration". Bei dem Feld "Enabled Services" muss der Punkt "Data angehakt werden. Danach muss man mit "tell nhttp quit" und "load nhttp" den Http Task von Domino durchstarten und die Data Services sollten funktionieren.

Nach der Konfiguration des Servers kann man schon verschiedene Informationen wie z.b. eine Übersicht aller Datenbanken auslesen. Um aber Daten aus einzelnen Datenbanken abrufen zu könnenn müssen diese Datenbanken noch für die Verwendung von Domino Data Services konfiguriert werden. Dazu muss man in den Datenbankeinstellungen unter Erweitert ganz unten den Zugriff erlauben. Man hat dabei die Auswahl ob man nur den Zugriff auf Ansichten, oder auch den Zugriff auf Dokumente erlauben will.

Falls man diese Einstellung nicht setzt erhält man beim Zugriff die Meldung "The Domino data service is not enabled for this database"

Zusätzlich zu der generellen Erlaubnis des Zugriffs auf die Datenbank muss dann auch noch bei jeder View bzw. Folder auf den man mittels REST Api zugreifen will der Zugriff mittels den Domino Data Services freigeschalten werden. Der Punkt befindet sich wieder in den erweiterten Einstellungen der Ansicht oder des Ordners.

Falls die Ansicht nicht freigeschalten wurde, bekommt man die Fehlermeldung "The Domino data service is not enabled for this view" beim Zugriff auf die Ansicht.

Im nächsten Post möchte ich dann zeigen wie einfach es ist auf Daten in einer Datenbank über die REST API zuzugreifen.