Grundlagen für ein Basis-Verständnis
Ohne gut dokumentierte Programmierschnittstellen wäre die Informationstechnologie, so wie wir sie heute kennen, nicht vorstellbar. So sorgt erst eine Programmierschnittstelle (englisch: Application Programing Interface - meist nur kurz API genannt) für die Kommunikation verschiedener Programme und Services untereinander. In Zeiten von verteilten Systemen und Web-Anwendungen, die immer stärker an Bedeutung gewinnen, steigt auch die Notwendigkeit, gewisse Standards und Gepflogenheiten einzuhalten. In diesem Artikel wollen wir einen ersten Überblick über die Chancen und Möglichkeiten gut dokumentierter APIs geben. Dabei wird der Artikel versuchen, das Basisverständnis für Programmierschnittstellen sprachunabhängig zu vermitteln. Zum grundlegenden Verständnis ist es erst einmal völlig egal, ob Ruby, Velato, PHP oder Java verwendet wird. Der Fokus wird dabei auf dem Wesen von Web-APIs liegen, die nach dem REST-Paradigma programmiert sind.
HTTP und REST
REST (Representational State Transfer) ist ein zustandsloses Programmierparadigma, das unter anderem bei Webservices zur Anwendung kommt. Anders als Alternativen wie etwa SOAP, WSDL oder RPC kommt REST ohne Methodeninformationen im Uniform Resource Identifier (URI) aus, da der URI keine Namen und Orte einer Ressource, wohl aber die Funktionalität angibt. Der große Vorteil von REST liegt darin, dass ein großer Teil der nötigen Infrastruktur bereits im World Wide Web vorhanden ist und viele Dienste bereits REST-konform sind. Dabei ist es ein verbreiteter Fehler anzunehmen, dass es sich bei REST um ein Protokoll (wie beispielsweise SOAP) handelt. Denn anders als SOAP ist REST nicht mit der Anwendung verknüpft. Aber auch REST benötigt eine einheitliche Schnittstelle. In den meisten Fällen kommt hier das HTTP-Protokoll zum Einsatz, da HTTP und REST sehr gut miteinander harmonieren und ergänzen.
Vereinfacht lässt sich sagen, dass es sich bei HTTP (Hypertext Transfer Protocol) um ein mögliches (in der Praxis das einzige) Anwendungsschichtprotokoll handelt. Mit der Verwendung von HTTP als Anwendungsschichtprotokoll ergibt sich automatisch, dass die möglichen Aktionen durch die HTTP-Methoden wie GET, POST, PUT und DELETE festgelegt werden. Bei der Verwendung von REST-konformem HTTP, also der Verwendung von REST als einheitlicher Schnittstelle, entfällt zugleich die Notwendigkeit anderer Protokolle, wie etwa SOAP.
Datenstruktur
Die bevorzugte Datenstruktur ist meist eine individuelle Vorliebe des jeweiligen Programmierers. In der Regel wird der Inhalt im XML- oder JSON-Format abgelegt. XML steht für Extensible Markup Language und bedeutet soviel wie erweiterbare Auszeichnungssprache. JSON, JavaScript Object Notation, bedeutet soviel wie JavaScript Objektschreibweise. In Abhängigkeit vom gewählten Inhaltsformat unterscheidet sich auch die jeweilige Datenstruktur. Auch wenn es persönliche Vorlieben gibt, sollten Sie sehr genau überlegen, welches Inhaltsformat besser zu Ihrem Projekt passt. Eine nachträgliche Änderung stellt Sie dann auch vor größere Änderungsnotwendigkeiten in der API selbst.
Authentifizierung
Wie bereits erwähnt, ist REST zustandslos. Wie lässt sich also verhindern, dass Benutzer auf etwas anderes zugreifen, als die erlaubten Inhalte? Selbstverständlich gibt es auch hier verschiedene Lösungsansätze, von denen OAuth 2.0 der derzeit am weitesten verbreitete ist. Trotzdem wollen wir einen kurzen Blick auf die alternativen Authentifizierungen werfen.
HTTP-Basic
Diese Variante ist am einfachsten zu implementieren, da es sich um die HTTP-Standardvariante handelt. Mit Benutzername und Passwort wird ein neuer Benutzer angemeldet und erhält Zugriff. Allerdings handelt es sich bei dieser Art der Authentifizierung auch um die unsicherste Variante, die Sie nur bei Verbindungen über SSL und HTTPS verwenden sollten.
JSON Web Tokens
Mit JSON ist ein einfaches Token-System möglich. Mit den Anmeldeinformationen erzeugt das System einen Token, der dann bei jedem Systemaufruf übermitteln werden muss. Die meisten JSON Web Tokens sind mit einem Verfallsdatum versehen, sodass sie regelmäßig erneuert werden müssen.
OAuth2
OAuth2 gilt als sichere und flexible Authentifizierungsmethode, was ihre große Beliebtheit erklärt. Genau wie JSON Web Token erzeugt OAuth2 ein zeitlich begrenzt gültiges Authentifizierungstoken, das bei jeder Anfrage mitgesendet wird. Die spezifischen Unterschiede von OAuth2 zum JSON Web Token liegen in der Raffinesse der technischen Details.
Versionierung
Je älter Ihre API wird, desto höher wird die Wahrscheinlichkeit, dass Sie etwas ändern wollen oder müssen, um beispielsweise zusätzliche Funktionen zu implementieren oder Sicherheitslücken zu schließen. Geben Sie aber bei jeder Änderung darauf Acht, Ihre Benutzer nicht zu verärgern, die sich teilweise auf vorhandene Features und bestehende Strukturen verlassen. Natürlich müssen sie die alte Version einer API nicht endlos bereithalten. Kündigen Sie Änderungen frühzeitig an und räumen den Benutzern so eine großzügigere Übergangsfrist ein. Darüber, wie eine Versionierung erfolgen sollte, gehen die Meinungen auseinander. Zwei der gebräuchlichsten Methoden wollen wir kurz aufzeigen:
URL basierte Versionierung
Diese Methode sieht recht naheliegend aus, erfordert aber einiges an Vorausschau. Schon die erste Version ihrer API müssen Sie mit dem Gedanken an mögliche Updates projektieren. Das klingt in der Theorie einfach, allerdings erfolgt die Schnittstellen-Versionierung in der Praxis häufig erst in einer späteren Projektphase.
Header basierte Versionierung
Wie der Name schon sagt, erfolgt die Versionierung bei dieser Methode durch einen Header, genauer gesagt den Accept Header. Wird im Header keine Version spezifiziert, wird automatisch die neueste verfügbare Version benutzt. Die Header basierte Versionierung gilt gemeinhin als die beste Wahl, aber es gilt dies für das einzelne Projekt abzuwägen.
API-Programmierung ist eine vielseitige Herausforderung
Natürlich kann ein kurzer, allgemeiner Artikel ohne auf Programmiersprachen einzugehen keine vollständige Einweisung in die API-Programmierung bieten. Halten Sie sich bei der Entwicklung eigener APIs ein paar Grundregeln vor Augen. Vermutlich ist jedes Problem, das Ihnen beim Entwickeln einer Schnittstelle begegnet, an anderer Stelle bei einem anderen Programmierer schon einmal aufgetreten. Seien Sie neugierig, schauen Sie sich vorhandene Lösungen an, übertragen Sie diese Ansätze falls passend auf Ihr Projekt und kommen Sie so zu einer optimierten Lösung.
Sie haben Fragen zu Schnittstellen-Programmierung? Sprechen Sie uns an! Bei mindtwo in Bonn beraten wir Sie gerne bei Ihrem Webprojekt.
