API Entwicklung - Übersicht und Best Practice

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.

Kontaktmöglichkeiten ein bzw. ausblenden Kontaktmöglichkeiten ausblenden

Sie möchten mehr über unsere Dienstleistungen erfahren oder haben spannende Projekte? Sprechen Sie uns an, wir helfen Ihnen gerne weiter!

Anruf unter +49 228 28695920
E-Mail an
Projektanfrage zum Formular

Wir verwenden Cookies, um Ihnen einen bestmöglichen Service zu bieten. Die Daten werden zur Optimierung unserer Webseite und zu Online-Marketingzwecken erhoben und zu statistischen Zwecken ausgewertet. Klicken Sie auf „OK”, um der Nutzung von Cookies zuzustimmen. Weitere Informationen finden Sie in unserer Datenschutzerklärung