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 Basis-Verständnis für Programmierschnittstellen sprachunabhängig zu vermitteln. Zum grundlegenden Verständnis ist es erst einmal völlig egal, ob Ruby, PHP oder JavaScript verwendet wird. Der Fokus wird dabei auf dem Wesen von Web-APIs liegen, die nach dem REST-Paradigma programmiert sind.

HTTP und REST: Symbiose für effektive Webservices

REST (Representational State Transfer) ist kein Protokoll wie SOAP, sondern ein architektonisches Paradigma, das den Zustand eines Webservice repräsentiert. Es benötigt keine Methodeninformationen in der Uniform Resource Identifier (URI), weil URI die Funktion, nicht den Namen und Ort einer Ressource angibt. RESTs Hauptvorteil ist seine nahtlose Integration mit dem bestehenden World Wide Web-Infrastruktur und die bereits weitverbreitete REST-Konformität vieler Dienste.

REST ≠ Protokoll
REST = Architektonisches Paradigma

Ein häufiges Missverständnis ist, dass REST spezifisch an eine Anwendung gebunden ist. Stattdessen agiert es unabhängig und benötigt nur eine einheitliche Schnittstelle. Häufig wird das HTTP-Protokoll verwendet, da HTTP und REST ein harmonisches Duo bilden, das sich gegenseitig ergänzt.

HTTP (Hypertext Transfer Protocol) fungiert als Anwendungsschichtprotokoll und definiert die möglichen Aktionen durch Methoden wie GET, POST, PUT und DELETE. Die Verwendung von REST-konformem HTTP eliminiert die Notwendigkeit von Protokollen wie SOAP.

Im Laufe der Jahre hat sich jedoch eine starke Alternative zu REST hervorgetan: GraphQL. GraphQL ist eine leistungsstarke Abfragesprache für APIs und eine Laufzeitumgebung, um diese Abfragen mit vorhandenen Daten auszuführen.

Im Gegensatz zu REST, das einen Endpunkt pro Ressource benötigt, bietet GraphQL einen einzigen Endpunkt für präzise Client-Anfragen. Dies ermöglicht es den Clients, spezifische Daten anzufordern und dabei Over- und Underfetching zu vermeiden, was es zu einer effizienteren Methode für den Zugriff auf Daten macht.

Datenstrukturen: Die DNA Ihrer API

Bei der Auswahl der richtigen Datenstruktur für Ihre API stehen Sie vor einer entscheidenden Entscheidung. Diese ist nicht nur eine Frage des persönlichen Geschmacks, sondern sollte auf den spezifischen Anforderungen Ihres Projekts basieren. Die Wahl kann erhebliche Auswirkungen auf die Flexibilität, Geschwindigkeit und Benutzerfreundlichkeit Ihrer API haben.

Häufig genutzte Datenformate sind XML und JSON. XML, die "Extensible Markup Language", ist eine erweiterbare Auszeichnungssprache, die dazu dient, strukturierte Daten in einer textbasierten Form zu repräsentieren. Sie ist bekannt für ihre strenge Typisierung und detaillierte Validierung, die es ermöglicht, komplexe und stark strukturierte Daten abzubilden. Dies kann besonders in Umgebungen nützlich sein, in denen Präzision und Kontrolle über die Datenstruktur von entscheidender Bedeutung sind.

Auf der anderen Seite steht JSON - die "JavaScript Object Notation". Sie ist ein leichtgewichtiges Daten-Austauschformat, das menschenlesbar und einfach zu generieren und zu verarbeiten ist. JSON hat sich in vielen Anwendungsfällen als das bevorzugte Format für APIs etabliert, vor allem wegen seiner leichten Verarbeitbarkeit und seiner nahtlosen Integration in JavaScript-basierte Anwendungen.

Die Entscheidung für das eine oder andere Format sollte auf einer genauen Überprüfung Ihrer spezifischen Anforderungen basieren. Bedenken Sie, dass eine nachträgliche Änderung des Datenformats oft eine umfangreiche Überarbeitung Ihrer API erfordert. Daher lohnt es sich, von Anfang an die richtige Wahl zu treffen.

Schließlich sollten Sie bei der Gestaltung Ihrer API auch die zukünftige Erweiterbarkeit berücksichtigen. Eine gut durchdachte Datenstruktur ermöglicht es Ihnen, neue Funktionen und Verbesserungen problemlos hinzuzufügen, ohne die bestehende Funktionalität zu beeinträchtigen.

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.

OAuth 2.0 und OpenID Connect

OAuth 2.0 ist ein Industriestandard-Protokoll für die Autorisierung. Es ermöglicht Drittanwendungen, den Zugriff auf Webressourcen im Namen eines Benutzers zu gewähren, ohne dessen Anmeldeinformationen preiszugeben. OAuth 2.0 konzentriert sich hauptsächlich auf die Bereitstellung einer Autorisierung und definiert vier Rollen: Ressourcenbesitzer, Client, Autorisierungsserver und Ressourcenserver.

Eine wichtige Anwendung von OAuth 2.0 ist die Erstellung von API-Schlüsseln, die Dritten den Zugriff auf bestimmte Ressourcen gewähren. Diese Schlüssel, auch als "Access Tokens" bekannt, haben eine begrenzte Lebensdauer und können nach Bedarf erneuert werden.

Obwohl OAuth 2.0 ein robustes Framework für die Autorisierung bietet, bietet es von sich aus keine Unterstützung für die Authentifizierung. Dies ist, wo OpenID Connect (OIDC) ins Spiel kommt. OIDC ist eine Identitätsschicht, die auf OAuth 2.0 aufbaut und es ermöglicht, dass Clients die Identität eines Benutzers basierend auf der Authentifizierung, die von einem Autorisierungsserver durchgeführt wird, überprüfen und grundlegende Profilinformationen über den Benutzer erhalten.

Zusammen bilden OAuth 2.0 und OpenID Connect eine mächtige Kombination für die sichere Handhabung von Authentifizierung und Autorisierung in modernen Webanwendungen und APIs. Sie bieten eine Reihe von Vorteilen:

• Delegation von Berechtigungen: OAuth 2.0 ermöglicht es Benutzern, den Zugriff auf ihre Daten auf sichere Weise zu delegieren, ohne ihre Anmeldeinformationen preiszugeben. Dies macht es ideal für Szenarien, in denen Drittanwendungen Zugriff auf Benutzerdaten benötigen.
• Single Sign-On (SSO): Mit OpenID Connect können Benutzer denselben Satz von Anmeldeinformationen verwenden, um sich bei mehreren Anwendungen anzumelden. Dies verbessert die Benutzererfahrung und reduziert die Anzahl der benötigten Anmeldeinformationen.
• Flexibilität: OAuth 2.0 definiert mehrere "Flows" (Autorisierungscode, implizit, Ressourcenbesitzer-Passwort-Anmeldeinformationen und Client-Anmeldeinformationen), die auf verschiedene Anwendungsfälle zugeschnitten sind. Dies bietet eine hohe Flexibilität für Entwickler.
• Identitätsinformationen: OpenID Connect ermöglicht den Austausch von Identitätsinformationen in Form von ID-Tokens. Diese sind ähnlich wie JWTs aufgebaut und enthalten Ansprüche über den Benutzer.

Wie bei JWTs sollten OAuth 2.0 und OpenID Connect sorgfältig implementiert werden, um potenzielle Sicherheitsprobleme zu vermeiden. Insbesondere sollten sensible Daten immer verschlüsselt werden, und geeignete Maßnahmen sollten ergriffen werden, um den Missbrauch von Access Tokens zu verhindern.

HTTP-Basic

HTTP-Basic ist eine einfache Authentifizierungsmethode, die in das HTTP-Protokoll integriert ist. Sie ermöglicht es Clients, Anfragen mit einem Authorization-Header zu senden, der Benutzername und Passwort in einem Base64-codierten Format enthält. Die Struktur des Headers ist wie folgt: Authorization: Basic base64(username:password).

Obwohl HTTP-Basic einfach zu implementieren und zu verwenden ist, hat es einige Einschränkungen, die berücksichtigt werden sollten:

• Keine eingebaute Sicherheit: HTTP-Basic bietet keine Sicherheit auf Anwendungsebene. Benutzernamen und Passwörter werden im Klartext über das Netzwerk gesendet, sofern sie nicht durch eine sichere Verbindung (z.B. HTTPS) geschützt sind.
• Keine Token-Verwaltung: Im Gegensatz zu OAuth 2.0 oder JWT bietet HTTP-Basic keine Möglichkeit, Sitzungen oder Tokens zu verwalten. Dies kann die Skalierbarkeit und Kontrolle über die Benutzersitzungen einschränken.
• Beschränkte Benutzerfreundlichkeit: Da HTTP-Basic keine Unterstützung für fortgeschrittene Authentifizierungsmerkmale wie Single Sign-On oder Mehrfaktor-Authentifizierung bietet, kann es in einigen Fällen weniger benutzerfreundlich sein.

Trotz dieser Einschränkungen kann HTTP-Basic in bestimmten Szenarien nützlich sein, insbesondere wenn Einfachheit und Bequemlichkeit Priorität haben und die Anwendung ausschließlich über sichere Verbindungen bereitgestellt wird. Es sollte jedoch immer mit Vorsicht verwendet werden und ist in der Regel nicht für APIs geeignet, die öffentlich im Internet ausgesetzt sind.

JSON Web Tokens (JWTs)

Ein JSON Web Token (JWT) ist ein offener Standard (RFC 7519), der es ermöglicht, Informationen sicher zwischen zwei Parteien zu übertragen. Ein JWT ist im Wesentlichen ein kompaktes, URL-sicheres Mittel zur Repräsentation von Ansprüchen, die zwischen zwei Parteien ausgetauscht werden. Die Ansprüche in einem JWT sind in JSON codiert, was das Token leicht zu verwenden und gleichzeitig sehr flexibel macht.

JWTs bestehen aus drei Teilen: einem Header, einem Payload und einer Signatur. Der Header gibt normalerweise den Token-Typ an (typischerweise JWT) und den verwendeten Signaturalgorithmus, wie HMAC SHA256 oder RSA. Der Payload enthält die "Claims" oder Aussagen über eine Entität (typischerweise den Benutzer) sowie zusätzliche Metadaten. Die Signatur ist ein Hash der kombinierten Header- und Payload-Daten, zusammen mit einem geheimen Schlüssel.

Es gibt einige Schlüsselvorteile bei der Verwendung von JWTs zur Authentifizierung:

• Selbstvalidierend: JWTs sind selbstvalidierend. Sie enthalten alle Informationen, die benötigt werden, um sie zu validieren. Sie benötigen keinen zusätzlichen Aufruf an den Server oder eine Datenbank, um die Gültigkeit des Tokens zu überprüfen.
• Kompakt: Aufgrund ihrer kompakten Größe können JWTs leicht über URL, POST-Parameter oder in HTTP-Headern übertragen werden. Sie sind daher besonders nützlich für Situationen, in denen ein Token in einer HTTP-Anforderung transportiert werden muss.
• Flexibel: JWTs können für alle Arten von Ansprüchen verwendet werden, einschließlich Authentifizierungsinformationen, Rollen und Rechten und sogar Benutzerdaten.

Trotz ihrer zahlreichen Vorteile ist es wichtig zu beachten, dass JWTs sorgfältig implementiert werden müssen, um Sicherheitsprobleme zu vermeiden. Insbesondere sollten sensible Informationen nie ohne Verschlüsselung in einem JWT gespeichert werden. Ferner sollte ein geeigneter Mechanismus zum Widerrufen oder Aktualisieren von Tokens vorhanden sein, da JWTs bis zum Ablauf ihrer Gültigkeitsdauer gültig bleiben.

Eine gängige Praxis ist die Verwendung von kurzlebigen Access-Tokens und längerlebigen Refresh-Tokens. Wenn das Access-Token abläuft, kann das Refresh-Token verwendet werden, um ein neues Access-Token zu erhalten, ohne dass der Benutzer sich erneut authentifizieren muss. Dies gewährleistet eine gute Balance zwischen Benutzerfreundlichkeit und Sicherheit.

Versionierung

Je älter Ihre API wird, desto höher wird die Wahrscheinlichkeit, dass Sie etwas ändern wollen oder müssen, um etwa 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 möchten wir kurz aufzeigen:

URL-basierte Versionierung

Einige APIs nutzen den URL-Pfad, um die Version anzugeben, etwa so: api/v1/users. Dieser Ansatz ist einfach und leicht zu verstehen, da die Version direkt in der URL sichtbar ist. Allerdings kann es auch zu Verwirrungen führen, wenn verschiedene Versionen von Endpunkten gleichzeitig existieren.

Header-basierte Versionierung

Die Header-basierte Versionierung verwendet HTTP-Header, um die API-Version anzugeben. Dieser Ansatz hält die URL sauber und erlaubt es, die Versionierung vom Rest der Anwendung zu trennen. Es kann jedoch schwieriger sein, da die Versionierungsinformationen nicht direkt in der URL sichtbar sind.

Parameter-basierte Versionierung

In der Parameter-basierten Versionierung wird die API-Version als Query-Parameter in der URL angegeben. Beispielsweise: api/users?v=1. Dieser Ansatz ist flexibel und leicht zu implementieren, kann jedoch zu unordentlichen URLs führen, wenn viele Parameter beteiligt sind.

In der Praxis setzten wir in nahezu allen Projekten auf das URL-basierte Versionierungs-Verfahren. Es gibt aber keinen "richtigen" oder "besten" Ansatz zur API-Versionierung - es hängt von den spezifischen Anforderungen und dem Kontext Ihrer Anwendung ab. Wichtig ist, dass Sie eine Methode wählen, die für Ihr Team und Ihre Nutzer gut verständlich und einfach zu verwenden ist. Stellen Sie zudem sicher, dass Änderungen gut dokumentiert sind und genügend Vorlaufzeit für die Anpassung an neue Versionen gegeben wird. So stellen Sie eine reibungslose und kontinuierliche Nutzung Ihrer API sicher.

API-First-Ansatz

Der API-First-Ansatz hat tatsächlich das Potenzial, die Entwicklungsdynamik grundlegend zu verändern. Hierbei handelt es sich um mehr als nur eine Denkweise - es ist ein Paradigmenwechsel, der die Art und Weise, wie Softwareanwendungen entworfen und entwickelt werden, neu definiert.

Was bedeutet API-First?

Beim API-First-Ansatz beginnt der Entwicklungsprozess mit der API-Spezifikation. Statt zuerst eine Anwendung zu entwickeln und dann eine API als Schnittstelle zu erstellen, dreht der API-First-Ansatz diese Reihenfolge um. Zuerst wird eine API erstellt, die den Rahmen für die Anwendungsentwicklung vorgibt. Anschließend wird die Anwendung selbst auf der Grundlage dieser API entwickelt.

Die Vorteile des API-First-Ansatzes

Es gibt eine Reihe von Vorteilen, die der API-First-Ansatz bietet:

• Konsistenz: Wenn eine API zuerst erstellt wird, können Entwickler sicherstellen, dass sie konsistent und standardisiert ist, bevor sie in die Anwendung integriert wird. Dies kann dazu beitragen, dass die Anwendung robuster und leichter zu pflegen ist.
• Wiederverwendbarkeit: APIs, die im Rahmen eines API-First-Ansatzes entwickelt werden, sind oft modular und wiederverwendbar. Dies bedeutet, dass sie in verschiedenen Kontexten und für verschiedene Zwecke verwendet werden können, was die Effizienz und Produktivität der Entwickler steigert.
• Zusammenarbeit: Der API-First-Ansatz fördert die Zusammenarbeit zwischen Backend- und Frontend-Teams. Beide Teams können gleichzeitig arbeiten, da das Frontend auf einer "Mock"-Version der API entwickelt werden kann, während das Backend-Team die tatsächliche API erstellt.
• Zukunftssicherheit: Da der API-First-Ansatz die API in den Mittelpunkt der Anwendungsentwicklung stellt, sind Anwendungen, die auf diese Weise entwickelt werden, besser auf zukünftige Änderungen und Erweiterungen vorbereitet.

Der API-First-Ansatz in der Praxis

Einige praktische Schritte zur Implementierung des API-First-Ansatzes könnten folgendermaßen aussehen:

1. Planung und Design: Definieren Sie die grundlegenden Anforderungen Ihrer Anwendung und entwerfen Sie die API-Spezifikation entsprechend. Tools wie OpenAPI oder Swagger können dabei helfen.
2. Entwicklung der API: Erstellen Sie die API entsprechend der Spezifikation. In dieser Phase können Sie auch eine "Mock"-Version der API für das Frontend-Team erstellen.
3. Testen der API: Testen Sie die API gründlich, um sicherzustellen, dass sie korrekt funktioniert und den Anforderungen entspricht. Tools wie Postman können dabei hilfreich sein.
4. Integration der API: Integrieren Sie die API in Ihre Anwendung und beginnen Sie mit der eigentlichen Anwendungsentwicklung.

Durch die Betonung der API als zentrales Element des Entwicklungsprozesses kann der API-First-Ansatz dazu beitragen, robustere, flexiblere und zukunftssichere Anwendungen zu schaffen. Mit dem API-First-Ansatz stehen Sie an der Spitze der modernen Softwareentwicklung.

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.