Skip to content

API-Dokumentationen mit ApiGen erstellen

Warum eigentlich API-Dokumentationen?

Eine gute Dokumentation ist wichtig für jedes Projekt, egal ob es sich dabei um ein von der Community entwickeltes Open Source-Tool handelt oder um eine für einen Kunden geschriebene Software. Eine API-Dokumentation erleichtert es Entwicklern, neu ins Projekt einzusteigen oder sich einen Überblick über alle relevanten Teile des Projekts zu verschaffen.

Ein weiterer Vorteil von API-Dokumentationen ist, dass sie sich schnell und automatisch generieren lassen. Dieser Schritt kann in den Build-Prozess integriert werden, so dass immer eine aktuelle, ggf. auch versionierte Dokumentation vorliegt. Sie sind sozusagen der leicht erfüllbare Mindeststandard für eine Dokumentation.

Denn, seien wir ehrlich, eine API-Dokumentation erklärt und veranschaulicht nicht (das machen Codebeispiele und handgeschriebene Dokumentationen), sondern ist eher eine Art Nachschlagewerk. Durch die immer besseren Funktionalitäten von IDEs verliert es sogar mittlerweile an Bedeutung. Ich persönlich schaue nur selten in einer API-Dokumentation nach, wenn ich das Projekt schon in meiner Entwicklungsumgebung vorliegen habe. Your mileage may vary ;-)

"API-Dokumentationen mit ApiGen erstellen" vollständig lesen

Zeit Online Content API und xkcd - Mein Hack vom Wochenende

Vor elf Tagen hat die Zeit Online mit einem kleinen Hackday ihr Content-API gelauncht. Die Zeit Online ist damit wohl die erste deutsche (Wochen-)Zeitung, die eine solche Programmierschnittstelle anbietet. International bieten z. B. der britische Guardian, die New York Times und USA Today einen ähnlichen Zugang zu ihren Inhalten an. Eine ausführliche Liste findet sich hier.

Da ich a) leider nicht beim Hackday in Berlin dabei sein konnnte und b) keine Idee für einen "Hack" hatte, hatte ich zunächst nur etwas mit dem API Explorer herumexperimentiert. Mein erster Eindruck war durchaus positiv, und bereits in den ersten Tagen wurden die ersten Apps geschrieben, die auf die Inhalte der Zeit zugreifen. Gelungene Beispiele sind etwa diese Visualisierung von Zeit-Artikeln auf einer Weltkarte oder diese Autorensuche in Sozialen Netzwerken.

xkcd-Comic
Der Original-Comic, cc by-nc Randall Munroe
Kurze Zeit später spülte mein Feedreader dann diesen Comicstrip herein, gezeichnet von Randall Munroe für seinen populären und genialen Webcomic xkcd. Im "Calendar of Meaningful Dates" zeigt die Größe eines Datums an, wie häufig es in englischsprachigen Büchern seit dem Jahr 2000 genannt wurde. Als Quelle gibt Munroe den Google Books Ngram Viewer an, mit dessen Hilfe sich übrigens auch Abfragen über deutschsprachige Bücher durchführen lassen.

Mir war sofort klar, dass sich ein solcher Kalender mit dem Zeit API nachbauen lassen müsste - und das sogar mit "Live-Daten". Also habe ich mich in den letzten Tagen zwischendurch daran gemacht, diese Idee umzusetzen. Die Anwendung, die auf Symfony2 basiert, fragt im Hintergrund (per Cronjob) bei der Zeit nach Artikeln, die ein Datum - z. B. "23. Mai" - enthalten, und speichert die Anzahl der Treffer. Anhand dieser wird nun die Kalenderdarstellung berechnet. Natürlich werden die Resultate gecachet, um die Server der Zeit zu schonen ;-) Und so sieht das Ergebnis aus, das unter http://calendarofmeaningfuldates.sperrobjekt.de/ zu finden ist:

Screenshot

Das ist natürlich nicht ganz so hübsch wie der handgezeichnete xkcd-Comic, dafür aber aktueller. Fährt man mit der Maus über ein Datum, wird rot die zugehörige Anzahl der Treffer angezeigt. Ein Klick leitet auf die Suchergebnisse bei Zeit Online weiter. Warum dort dann jeweils etwas mehr Treffer erzielt werden, kann ich nicht nachvollziehen; das Verhältnis der Daten untereinander scheint aber zu stimmen. Weil die Anwendung eben ein schneller "Hack" ist, sind solche Kleinigkeiten IMHO zu verschmerzen.

Die Ergebnisse sind übrigens auch ganz interessant: Am häufigsten genannt wird der 1. Januar, wie überhaupt der erste und letzte Tag jedes Monats häufiger auftaucht als die übrigen Tage. Drei Daten stellen eine Ausnahme dar: Der 17. Juni, der 20. Juli sowie der 11. September. Letzterer tritt auch im Original groß hervor. Der 17. Juni war bis zur Wende der Tag der Deutschen Einheit, und das Archiv der Zeit reicht ja zurück bis 1946. Aber was ist mit dem 20. Juli? Hat jemand für dieses Datum eine Erklärung? Mir ist bisher noch keine überragende Begebenheit für diesen Tag eingefallen.

Hier geht's direkt zum Calendar of Meaningful Dates - German ZEIT Edition.

Der halboffene Haushalt

Visualisierung des Bundeshaushalts auf offenerhaushalt.de

In The state of mapping APIs wirft Adam DuVander einen Blick auf die wichtigsten momentan verfügbaren Mapping APIs (vergisst dabei aber OpenLayers!). Er stellt fest, dass es immer einfacher werde, Karten zu erstellen, dass es aber immer noch zu schwierig sei, an die Daten heranzukommen, um die Karten mit sinnvollen Informationen anzureichern.

In diesem Zusammenhang weist er auch darauf hin, dass es immer noch zu kompliziert sei, so genannte Choroplethenkarten aus Datenquellen zu erstellen. Was ein Choroplethenkarte ist, musste ich erst einmal nachschlagen. Im Prinzip sind das eingefärbte thematische Karten, auf denen beispielsweise Landkreise nach Häufigkeit bestimmer Eigenschaften unterschiedlich eingefärbt werden, wie sie auch dpa Regiodata anbietet. Da kommt dann auch wieder die Open Government-Bewegung ins Spiel.

Denn was bringt uns das beste Toolkit, um solche Karten einfach und schnell erstellen zu können, wenn wir an die zugrundeliegenden Daten gar nicht herankommen? Welche Probleme das Fehlen der Daten mit sich bringt, zeigt ein aktuelles Projekt auf. Unter OffenerHaushalt wird der Bundeshaushalt schön visualisiert und interaktiv bis auf die einzelnen Posten heruntergebrochen erfahrbar gemacht. Einen Haken hat die Sache aber, denn:

Die von OffenerHaushalt.de verwendeten Daten entstammen der Webseite des Bundesministeriums der Finanzen. Leider stehen die Haushaltsdaten nicht in einem offenen, maschinenlesbaren Datenformat zur Verfügung. Wir mussten daher auf einer maschinelle Auswertung der angebotenen HTML-Dokumente ("screen scraping") zurückgreifen.

Das ist schon ganz schön bitter und der Qualität der Daten nicht gerade förderlich. Immerhin stellt das Projekt die so gewonnenen Daten in maschinenlesbarer Form zur Verfügung, so dass sie auch von Dritten weiterverarbeitet werden können. Ich würde ja gern auch die Länderhaushalte sehen oder den Bundeshaushalt als multi-level pie chart. Eine freie Library, die so ein Diagramm erzeugen kann, habe ich aber noch nicht gefunden. Mal weitersuchen ...

Freier Routing-Dienst von MapQuest

Mapping ist ja einfach nur ein Hobby von mir. Seit ich vor einigen Jahren die Community-betriebene Openstreetmap entdeckt habe, faszinieren mich die unterschiedlichen Facetten dieses Themenkomplexes ungemein. Regelmäßig lese ich einige Mapping-Blogs, unter anderem OpenGeoData. Dort wurde gestern ein Hinweis auf ein neues, offenes Routing-API von MapQuest gepostet. Routing und Navigation waren bisher eigentlich immer so die Punkte, die ich als noch zu jung und experimentell und meist für den Praxiseinsatz unbrauchbar empfand. Das könnte sich nun ändern, denn der frei zugängliche Routingdienst von MapQuest setzt im Hintergrund auf Daten der Openstreetmap.

Interessehalber habe ich die Dokumentation mal überflogen und dieses Beispiel minimal abgewandelt, um den Dienst testen zu können. Funktionert 1A! So sieht das Ergebnis aus (bitte auf "Route berechnen" klicken)

API-Schlüssel in YQL Storage sicher speichern

YQL LogoVorhin habe ich etwas mit YQL herumgespielt und versuchsweise das API von last.fm angezapft. Der Aufruf der einzelnen Methoden setzt einen API-Schlüssel ("API Key") voraus, den man problemlos bei last.fm beantragen kann. Ich habe mich lange gefragt, wie ich diese Methoden mit reinem Javascript auf einer öffentlich zugänglichen Webseite aufrufen kann, ohne meinen API Key ebenfalls öffentlich zu machen. Denn beim Testen innerhalb der YQL Console ist er Teil des SELECT-Statements, auf meiner Seite darf er das nicht mehr sein. Im folgenden zeige ich, aufbauend auf einem Artikel von Nagesh Susarla, was zu tun ist, damit man den geheimen API-Schlüssel geheim halten und dennoch für seine YQL-Abfragen nutzen kann.

Damit kann ich beispielsweise meine wöchentlichen Top-Künstler von last.fm abrufen kann, reichen mir ein paar Zeilen Javascript-Code, einen eigenen Webserver benötige ich dafür gar nicht. Als Grundlage dient mir das offizielle YQL-Tutorial First YQL Application, das ihr euch vielleicht ansehen solltet, falls ihr noch nie mit YQL zu tun hattet. Die Daten, sprich meine Top-Künstler, beziehe ich aus der Community Table lastfm.user.getweeklyartistchart (dort auf Test klicken).

Um nun an meine Liste heranzukommen, schicke ich folgende Abfrage ab:

select '' from lastfm.user.getweeklyartistchart where user = 'numblog' and apikey = 'APIKEY'

In der YQL Console ausführen (ihr benötigt einen gültigen API Key) - Hinweis: Die Hochkommata um das Sternchen bitte weglassen; die stehen da nur, weil sonst das Syntax-Highlighting kaputt geht.

Wollte ich diese Abfrage in meine Webseite einbinden, wäre der API Key für alle lesbar:

Ich will natürlich vermeiden, dass Dritte mit meinem API Key auf last.fm zugreifen. Hier kommt Yahoo! Sherpa ins Spiel, ein Key-Value-Store in der Cloud. Dieser kann ebenfalls via YQL angesprochen werden und bietet die üblichen Vorteile (und Nachteile) einer Cloud-Lösung. Zwei Open Data Tables werden angeboten, yql.storage und yql.storage.admin, wobei yql.storage.admin die Tabelle unserer Wahl ist, weil sie nur nach erfolgter OAuth-Anmeldung oder über die YQL Console befüllbar ist. Mehr Info dazu bietet die Dokumentation.

Aber gehen wir noch einmal einen Schritt zurück. Anstatt den API Key in der WHERE-Bedingung zu übergeben, könnten wir auch folgendermaßen vorgehen und die Variable schon vor unserer Abfrage setzen:

use 'http://www.datatables.org/lastfm/lastfm.user.getweeklyartistchart.xml' as lastfm.user.getweeklyartistchart;
set apikey='APIKEY' on lastfm.user.getweeklyartistchart;
select "" from lastfm.user.getweeklyartistchart where user = 'numblog';

Wenn wir dies nun mit der Tabelle yql.storage.admin verbinden und in der YQL Console (in eingeloggtem Zustand, ihr benötigt also auch einen Yahoo!-Account) die Daten mit dem entsprechenden Statement in die Cloud schreiben:

insert into yql.storage.admin (value) values ("use 'http://www.datatables.org/lastfm/lastfm.user.getweeklyartistchart.xml' as lastfm.user.getweeklyartistchart;
set apikey='APIKEY' on lastfm.user.getweeklyartistchart;")

dann erhalten wir dem folgenden ähnliches XML zurück:

    
        store://I2KUjXfoobarAzIw0v3vfv
        store://p6QZPnGmgyoafoobarNimz
        store://jTfoobarMLleWbJoMY8phd
    

Dieses Ergebnis solltet ihr euch gleich mal in einen Editor kopieren, denn das benötigen wir gleich wieder zur Abfrage auf unserer Webseite. Kurz erklärt:

  • Der execute-Schlüssel kann nur zur Ausführung von Abfragen verwendet werden. Die hinterlegten Daten werden nicht ausgegeben.
  • Der select-Schlüssel sollte geheim bleiben, denn damit lassen sich die Einträge aus yql.storage auslesen.
  • Der update-Schlüssel erlaubt das Verändern dieser Einträge; somit sollte auch er geheim bleiben.
Mithilfe des execute-Schlüssels, den wir als Umgebungsvariable übergeben, lässt sich unsere Abfrage nun ohne Angabe des API Key ausführen:

Ihr könnt in der YQL Console auch gern die Sicherheit des execute-Schlüssels testen und werdet einen Permission-Error zurückbekommen:

select * from yql.storage where name='store://I2KUjXfoobarAzIw0v3vfv'

In der YQL Console ausführen.

Somit steht dem clientseitigen Anzapfen diverser APIs nichts mehr im Wege, auch wenn ein API Key verlangt wird. Momentan gibt es bereits weit über 800 Open Data Tables, über die Daten von den verschiedensten Diensten abgerufen werden. Viele davon sind frei zugänglich, andere benötigen einen API Key. Fragt ihr diese vom Server aus ab, stellt das kein Problem dar. Eine rein clientseitige Lösung im Browser hat aber auch ihren Charme. Es wird kein Server benötigt und daher auch nicht belastet, Yahoo! übernimmt im Hintergrund viel Arbeit (Caching, Fehlerbehandlung, ...) für euch, und möglicherweise ist alles viel schneller. Und jetzt auch sicher.

Hier die simple Ausgabeliste meines einfachen Beispiels:

tweetbackcheck