Als Metasuche für Reisedienstleistungen sind wir glückliche Nutzer, aber auch Opfer von APIs sehr unterschiedlicher Couleur und Qualität geworden. Diese Erfahrung hat uns sehr dabei geholfen, eine eigene API zu entwickeln. Die Key-Learnings sollen in diesem Artikel beschrieben werden. Ich beziehe mich in diesem Artikel auf Web-Services, die über eine API Grundfunktionalitäten aus dem eigenen Produkt anderen Entwicklern zur Verfügung stellen möchten. Grundsätzliches aus diesem Dokument gilt auch für APIs, wie sie in Betriebssystemen oder Programmiersprachen verwendet werden; einzelne Punkte beziehen sich aber speziell auf RESTful Web APIs.

Grundlegendes

Eine gute API birgt Potential zur Verbreitung eines Produkts. Flickr, Twitter oder Amazon erreichten sehr große Marktdurchdringung auch durch eine sehr große Anzahl an unterschiedlichen Clients sowie ungeplanten Anwendungen und machen wesentliche Umsätze durch ihre API. Auf der anderen Seite können einmal veröffentlichte APIs nur schwer geändert oder gar zurückgezogen werden: Applikationen Dritter funktionieren nicht mehr, oder nicht mehr richtig oder sind im schlimmsten Fall destruktiv.

Interfaces und deren Dokumentation sollten allen zugänglich und auch so konzipiert sein: Ist das Produkt interessant genug, lässt sich der Zugang zur Dokumentation sowieso nicht kontrollieren.

Der Prozess der Spezifikation

Die Spezifikation einer API sollte nicht zu lange dauern. Oft passt die grobe Spezifikation der API auf ein Whiteboard und umfasst weniger als zehn Methoden. Agilität ist zu Beginn der Entwicklung wichtiger als Vollständigkeit. Sich bei der Spezifizierung der eigenen API zurücknehmen zu können bedeutet auch, dass man die Kernfunktionen seines Produktes verstanden hat.

Schickt man hingegen Entwickler eine Woche in einen Raum, um über die Spezifikation der API zu diskutieren, wird die API meist um ein Vielfaches komplexer und auch genauso umgesetzt. Die Entwickler haben bis dahin so viel Herzblut und Arbeit in die API gesteckt, dass sie sie auch verteidigen und mit Code ausfüllen – unabhängig davon, ob oder wann sich herausstellt, dass die Spezifikation nicht hinreichend, die API umständlich oder die Dokumentation völlig unverständlich ist.

RESTful zu arbeiten nimmt sowohl den eigenen Entwicklern als auch den zukünftigen Nutzern viel Arbeit ab und gibt ein gutes Schema für die Spezifikation vor. Das HTTP Protokoll spezifiziert bereits eine große Menge der eigenen API:

• Daten werden ausschließlich via GET abgeholt
• Daten werden ausschließlich via POST erzeugt und via PUT geändert
• HTTP Status Codes decken den größten Teil der Fehler- und Erfolgsnachrichten ab: Schaut euch auch mal die Liste der HTML-Status Codes oder die Übersicht von Alan Dean an.

Die API sollte als Bezeichner einfache Verben und Nomen benutzen. Gute Worte sind um Beispiel “origin”, “destination”, “result”, “offer” oder “price”. Schlechte Worte sind hingegen etwa”DropDownListMarketMonth1″ oder “DropDownListMarketDateRange2″.

Eine API sollte möglichst klar und konsistent sein: Wo ist der Unterschied zwischen getResult und fetchResultSet? Außerdem sollten die Reihenfolgen der Parameter einem einheitlichen Schema folgen: Unheitlich wäre zum Beispiel findCustomers(kriterium, maxAnzahl, sortiereNach) vs. findProducts(kriterium, sortiereNach, maxAnzahl).

Entwicklung

Bevor die API mit Code gefüllt wird, sollte sie idealerweise bereits vollständig getestet bzw. spezifiziert sein zum Beispiel durch Unit-Tests oder rSpec. Nirgendwo ist es einfacher, Behavior Driven Development (BDD) umzusetzen, als bei einer API. Sehr hilfreich ist es (auch für die Spezifikation), wenn bereits ein oder besser mehrere Anwendungsfälle und Clients bekannt sind (iPhone App, Android App, Desktop Widget etc.). Als hilfreich hat sich herausgestellt, ganz zu Beginn der Entwicklung einen Client für die Kommandozeile auf Basis der API zu entwickeln. So stellt man sicher, dass der Kern des Produktes abgebildet werden kann.

Funktionen wie Sortierung, Filterung, sekundäre Features etc. sind Kür, nicht Pflicht: If in doubt, leave it out. Einmal eingeführte Features müssen unter Umständen für Jahre unterstützt und gepflegt werden. Und wenn selbst die eigenen Entwickler es als zu anstrengend empfinden, die eigene API zu nutzen, muss sie neu spezifiziert werden.

Ein Wort zu Ausgabeformaten: JSON ist ein ausreichend verbreitetes und vor allem einfaches Format, sodass es aus meiner Erfahrung Sinn macht, als erstes Ausgabeformat JSON einzusetzen; sowohl JavaScript als auch das iPhone kommen sehr gut damit zurecht. Später sollten dann natürlich auch XML und je nach Bedarf HTML zur Verfügung gestellt werden. Insbesondere für Fehlermeldungen gilt: Eine API sollte immer das Format zurückliefern, das auch angefordert wurde. Passiert dies nicht, vervielfacht sich der Arbeitsaufwand für den API-Nutzer. Damit reduziert sich auch die potenzielle Zielgruppe bzw. steigt der Arbeitsaufwand im Support.

Dokumentation und Support

Die Dokumentation sollte leicht zugänglich sein – eine Autorisierung bzw. Authentifizierung für die Dokumentation ist nur selten sinnvoll. Sie sollte leicht zu lesen sein und eine Einleitung zu den Grundgedanken haben (“um von A nach B zu kommen, muss man Methoden X und Y aufrufen”). Generell sollte die Dokumentation wirklich immer während der Entwicklung passieren. Hier zeigt sich, ob die Spezifikation gut war: Ist der entstehende Beispiel-Code leicht verständlich? Ist es einfach, Beispielergebnisse zu produzieren? Kann sich der Entwickler noch an den Sinn aller Parameter erinnern? Passt die Dokumentation einer Methode in einen Absatz?

Exceptions und Fehlermeldungen sollten dokumentiert sein. Welche Formate haben Fehlermeldungen? Wie kann der API-Nutzer Fehlermeldungen seinem eigenen Kunden weitergeben? Es sollte einen Ansprechpartner geben, der mit Telefonnummer und Mail-Adresse in der Dokumentation genannt ist. Wird die User-Basis größer (mehr als drei Parteien) lohnt sich ein Forum bzw. eine öffentliche Mailingliste (auch zur Ideenfindung und Selbsthilfe).

Pflege und Versionierung

Im besten Fall hat die entwickelte API viele Nutzer gefunden und muss weiterhin unterstützt werden. Durch die bestehenden Unit-Tests kann trotz Entwicklung am Hauptprodukt weiterhin sichergestellt werden, dass die API wie dokumentiert funktioniert.

Sollen neue Methoden zur API hinzugefügt werden oder Ergebnisse mehr Details aufweisen, reicht es meistens, die bestehende Schnittstelle zu erweitern. Da aber nicht alle Anwendungsfälle von vornherein abgedeckt werden können oder sich Fehler eingeschlichen haben können, die erst spät erkannt werden, sollte eine Versionierung schon zu Beginn der Entwicklung eingeplant sein. Es macht durchaus Sinn, schon von Anfang an die Version in den URLs aufzuführen. Um eine Schnittstelle “aus einem Guss” zu entwickeln, ist es sinnvoll API-Dokumentation und -Pflege in die Hände desselben Entwicklers zu geben.

Fazit

Eine API ist für die Ewigkeit gemacht und sollte auch so entwickelt werden. Nicht alles trifft man richtig beim ersten Versuch, eine Versionierung ist unumgänglich. Alle Best Practices aus der Software-Entwicklung treffen aufeinander: BDD, Tests, Dokumentation und Voraussicht bei der Spezifikation. Die API ist ein Aushängeschild für ein Unternehmen und kann interessierte Entwickler besser anlocken als eine spannende Job-Anzeige. Ein Beispiel der Travel IQ API.

Über den Autor:

Tim Lawrenz ist seit 2008 CTO bei Travel IQ – einer Meta-Suchmaschine im Reisebereich, welche die Angebote der besten Reise–Webseiten in wenigen Sekunden durchsucht.

Tim studierte Informatik an der TU-Darmstadt und hat für mehrere national und international tätige IT-Firmen gearbeitet.