SalesLentz::DevTeam

Das SalesLentz::DevTeam ist das intere Entwicklerteam von Sales-Lentz – eines der größten Reiseunternehmen in Luxemburg.

Mehr erfahren »

Innerhalb einer Rails-Applikation werden immer häufiger API’s definiert, um die Kommunikation mit der Applikation zu ermöglichen. Dies kann zum Beispiel der Bereitstellung von Schnittstellen für Dritte dienen, oder aber auch zur Interaktion mit einem Client (Browser) über Ajax. Auf der einen Seite muss eine API getestet werden, ebenso muss es auf der anderen Seite auch eine Dokumentation geben, aus der ersichtlich ist, wie man mit der API kommunizieren kann, und welche Funktionen überhaupt bereitgestellt werden. Dies ist insbesondere dann wichtig, wenn man keinen Zugang zum Quelltext hat, z.B. dann wenn Dritte die Schnittstelle anbinden wollen.

Definition und Test einer API

Das Gem rspec_api_documentation (Quelltext auf Github) ermöglicht es, die Anforderung an eine API mit RSpec und der eigens bereitgestellten DSL zu formulieren. Dadurch ist es möglich, die API innerhalb der RSpec Testsuite auf korrekte Funktion hin zu überprüfen.

put "/api/v1/customers/123/orders/789" do
  parameter :state, "new status of the order"
  let(:state) { "paid" }
  example "Set the order state to 'paid'" do
    do_request
    status.should eq 200
    response_body.should == "new order state: paid"
  end
end

Dieses Beispiel definiert das Updaten einer Bestellung eines bestimmten Kunden. Der zu testende Request wird mittels HTTP-PUT an /api/v1/customers/123/orders/789 gesendet. Verlangt ein Request weitere Paramter, werden diese entsprechend definiert. Dabei wird angegeben, welcher Paramter erwartet wird, sowie eine kurze Beschreibung des Parameters selbst. Dies dient in erster Linie der Dokumentation. Über entsprechende Zuweisungen mit let(:parameter_name) {} kann jedem Parameter ein entsprechender Wert zugewiesen werden. Im nachfolgendem Testaufruf wird der definierte Request ausgeführt, und die Erwartung an die Response überprüft.

Weitere Möglichkeiten zum Testen und Umfang der DSL sind in der Dokumentation und im Wiki beschrieben. Eine Anleitung zum installieren des Gems ist dort ebenfalls vorhanden.

Ausführen der Tests

Die Tests können ganz normal mittels bundle exec rspec ausgeführt werden.

Dokumentation der API

Neben dem Testen der API kann dieses Gem auch eine sehr gute Dokumentation erzeugen. Grundlage dazu sind die geschriebenen Tests der API, sowie die Requests und Responses beim Ausführen der Tests. Wie in der Beispiel-Dokumentation zu sehen, wird für jede API Funktion aufbereitet, welche Parameter erwartet werden, was als Request gesendet wurde, und wie die erhaltene Response aufgebaut ist.

Am Beispiel von Creating an order kann man erkennen, was im Request die Headers waren, welcher Body gesendet wurde, und auf welche Route (URL) zugegriffen wird. Gleiches gilt für die erhaltene Response. Dort erkennt man den empfangenen Header, die Daten im Body und den HTTP Statuscode der Anfrage.

Erzeugen der Dokumentation

Angenommen, die API Specs liegen im Verzeichnis spec/api innerhalb einer Rails-Applikation. Folgender Befehl für diese Tests aus und erzeugt dann die entsprechende Dokumentation. In der default Einstellung wird diese im Verzeichnis docs gespeichert und kann dort über die ìndex.html aufgerufen werden.

bundle exec rspec ./spec/api --format RspecApiDocumentation::ApiFormatter

Weiterführende Informationen

Neben dem Testen, Dokumentieren und Implemetieren einer API stellen sich evtl. noch weitere Fragen rund um das Thema API Design, Versionierung und Sicherheit. Ein erster Ansatz dazu sind die Screencasts von Ryan Bates.

Alle verwendeten Links sind nochmal hier aufgeführt:

verfasse einen Kommentar