Was ist API-Design?

Das API-Design beinhaltet Entscheidungen über API-Endpunkte, Anfrage- und Antwortformate, Protokolle und die Art und Weise, wie APIs mit anderen Anwendungen und Verbrauchern kommunizieren. Das API-Design spielt auch eine wichtige Rolle bei der API-Governance.

API-Governance bezieht sich auf die umfassenden Standards, Richtlinien und Praktiken, die bestimmen, wie ein Unternehmen seine APIs entwickelt, bereitstellt und nutzt. Ein effektives API-Design führt zu APIs, die diesen vorgegebenen Richtlinien entsprechen, mit einer robusten, aktuellen Dokumentation, die erklärt, wie die API funktioniert. Die Ergebnisse sind gut konzipierte APIs, die eine bessere Wiederverwendbarkeit, Skalierbarkeit und Kompatibilität aufweisen und ihren Endnutzern eine bessere Erfahrung bieten.

Es gibt viele verschiedene API-Anwendungsfälle und zahlreiche Ansätze für das API-Design, wobei einige Protokolle, Architekturstile und Sprachen für bestimmte Aufgaben oder Anwendungsfall besser geeignet sind als andere.

Die zunehmende Verwendung von Web-APIs hat zur Entwicklung und Verwendung bestimmter Protokolle, Stile, Standards und Sprachen geführt. Diese Strukturen bieten Benutzern eine Reihe von Parametern oder API-Spezifikationen, die akzeptierte Datentypen, Befehle, Syntax und mehr definieren. Tatsächlich erleichtern diese API-Protokolle einen standardisierten Datenaustausch.

Zu den gängigen Protokollen, Architekturstilen und Sprachen gehören:

• SOAP (Simple Object Access Protocol)
• Remote Procedure Call (RPC)
• WebSocket
• REST (Representational State Transfer)
• GraphQL

Die Auswahl der richtigen Struktur für eine neue API ist ein wichtiger Aspekt des Designprozesses. Diese Protokolle, Architekturstile und Sprachen sind nicht unbedingt besser oder schlechter als die anderen. Es sind unterschiedliche Tools für unterschiedliche Aufgaben.

SOAP ist eine leichtgewichtige XML-basierte Messaging-Protokollspezifikation, die es Endpunkten ermöglicht, Daten über eine Reihe von Kommunikationsprotokollen wie SMTP (Simple Mail Transfer Protocol) und HTTP (Hypertext Transfer Protocol) zu senden und zu empfangen. SOAP ist unabhängig, was es SOAP-APIs ermöglicht, Informationen zwischen Anwendungen oder Softwarekomponenten auszutauschen, die in verschiedenen Umgebungen ausgeführt werden oder in verschiedenen Sprachen geschrieben sind.

Im Vergleich zu anderen Arten von APIs werden SOAP-APIs tendenziell formalisierter und strukturierter entwickelt. SOAP-APIs gibt es bereits seit den 1990er Jahren. Es handelt sich um ein älteres, etabliertes Format, das jedoch langsamer ist als modernere Architekturen wie REST. 

SOAP funktioniert durch die Codierung von Daten im XML-Format und unterstützt keine Datenübertragung in anderen Formaten. Andererseits benötigen SOAP-APIs nicht unbedingt HTTP, um Nachrichten zu transportieren, was ihnen mehr Flexibilität bei der Verschiebung von Daten gibt. SOAP gilt als sicherer als einige andere Protokolle, sodass SOAP-APIs für Systeme geeignet sind, die sensible Daten verarbeiten.

Remote Procedure Call (RPC) ist ein Protokoll, das das im Betriebssystem verwendete High-Level-Kommunikationsparadigma bereitstellt. RPC implementiert ein logisches Client-zu-Server-Kommunikationssystem, das speziell für die Unterstützung von Netzwerkanwendungen entwickelt wurde. Das RPC-Protokoll ermöglicht es Benutzern, mit entfernten Prozeduren so zu arbeiten, als wären die Prozeduren lokal. Dadurch eignen sie sich gut für Situationen, die viele Client/Server-Interaktionen erfordern.

RPC-APIs können weiter in XML-RPC, JSON-RPC und gRPC unterteilt werden. XML-RPC ist ein Remote Procedure Call, der ein bestimmtes XML-Format zur Übertragung von Daten verwendet. Sie sind sogar älter als SOAP-APIs, aber einfach und schlank. JSON-RPC ist ein Remote Procedure Call, der JSON (JavaScript Object Notation) zur Übertragung von Daten verwendet. Da JSON universelle Datenstrukturen verwendet, kann es mit jeder Programmiersprache verwendet werden. 

gRPC ist ein leistungsstarkes Open-Source-RPC-Framework, das ursprünglich von Google entwickelt wurde. gRPC verwendet das Netzwerkprotokoll HTTP/2 und das Datenformat Protocol Buffers und wird häufig zur Verbindung von Services in einer Microservices-Architektur verwendet.

WebSocket-APIs ermöglichen die bidirektionale Kommunikation zwischen Client und Server. Bei dieser Art von API muss nicht für jede Kommunikation eine neue Verbindung aufgebaut werden, sondern es ist ein kontinuierlicher Austausch möglich, sobald die Verbindung hergestellt ist. Das macht Web Socket APIs ideal für die Echtzeitkommunikation. 

Live-Chat, Echtzeit-Standortverfolgung und Datenübertragung sind hervorragende Anwendungsfälle für WebSocket-APIs. WebSocket-APIs sind auch für die Datensynchronisation nützlich, da sie eine einheitliche und aktuelle Darstellung von Daten über mehrere Geräte oder Systeme hinweg ermöglichen. Änderungen werden in Echtzeit aktualisiert, ohne dass bei jeder Änderung eine neue Verbindung hergestellt werden muss.

REST ist eine Reihe von Web-API-Architekturprinzipien. REST-APIs– auch bekannt als REST-konforme oder RESTful APIs – sind APIs, die bestimmte REST-Architekturbeschränkungen einhalten. REST-APIs verwenden HTTP-Methoden wie GET, PUT, HEAD und DELETE zur Interaktion mit Ressourcen. REST stellt Daten als Ressourcen zur Verfügung, wobei jede Ressource durch eine eindeutige URI repräsentiert wird. Clients fordern eine Ressource an, indem sie deren URI angeben. REST-APIs sind statusunabhängig – sie speichern keine Clientdaten zwischen Anfragen.

RESTful-APIs sind beliebt, weil sie leichtgewichtig, flexibel und benutzerfreundlich sind. Sie unterstützen den Nachrichtentransport in verschiedenen Formaten (z. B. einfacher Text, HTML, YAML, XML und JSON) vollständig und unterstützen auch Caching. Dies macht sie zwar in einer Vielzahl von Kontexten nützlich, aber für einige Stationen ist eine bestimmte Sprache oder ein bestimmtes Protokoll erforderlich, um eine Aufgabe effizient zu erledigen.

GraphQL ist eine Abfragesprache und API-Laufzeit, die Meta 2012 intern entwickelt hat, bevor sie 2015 Open Source wurde. GraphQL ermöglicht es Benutzern, API-Anfragen mit nur wenigen Zeilen zu stellen, anstatt auf komplexe Endpunkte mit vielen Parametern zugreifen zu müssen. Diese Fähigkeit kann die Erstellung und Beantwortung von API-Anfragen erleichtern, insbesondere von komplexeren oder spezifischen Anforderungen, die auf mehrere Ressourcen abzielen.

Da Meta diese Abfragesprache entwickelt hat, um seine mobilen Anwendungen effizienter zu machen, ist es sinnvoll, dass GraphQL-APIs auch für mobile Anwendungen nützlich sind. Da sie einen einzigen Einstiegspunkt bieten, können GraphQL-APIs die Ladezeiten verkürzen, indem sie Daten abfragen, ohne mehrere Anfragen an den Server stellen zu müssen. 

Es gibt vier Hauptphasen des Designprozesses für eine API:

• Plan
• Entwicklung
• Test
• Deploy

All diese Schritte erfordern die Zusammenarbeit zwischen wichtigen API-Stakeholdern. Auch wenn einige Schritte für bestimmte Stakeholder besser geeignet sind als für andere, sollte das API-Design während des gesamten Prozesses kollaborativ erfolgen. Dies hilft Entwicklern, zusätzliche Funktionen zu vermeiden, die das Programm nicht benötigt, und beschleunigt den Entwicklungsprozess insgesamt.

Der erste Schritt eines jeden Projekts besteht darin, dass alle Beteiligten festlegen, welche Art von neuer API sie erstellen möchten. Eine öffentlich zugängliche API, mit der Kunden in einer E-Commerce-Umgebung interagieren können, hat andere Design- und Funktionsanforderungen als eine API, die intern für einen Workflow verwendet werden soll. Es ist wichtig, dass alle Stakeholder die Anwendungsfälle für eine potenzielle API verstehen, bevor mit der Entwicklung begonnen wird.

Wenn sie verstehen , was ein Unternehmen entwickelt (und warum), erhalten Entwickler eine bessere Vorstellung davon, wie es erstellt werden soll, einschließlich der zu verwendenden Protokolle. Wenn diese potenzielle API beispielsweise Echtzeitkommunikation erfordert, wissen die Entwickler, dass sie bei der Erstellung WebSocket verwenden könnten, da dieses Protokoll für diesen Zweck gut geeignet ist. 

Sobald die Stakeholder eine klare Vorstellung davon haben, was die API sein wird und wie sie funktioniert, kann mit der Entwicklung begonnen werden. Im Laufe des Prozesses der API-Entwicklung definieren die Entwickler die API-Endpunkte, entwerfen das Datenmodell für die API, stellen sicher, dass die API die API-Sicherheitsrichtlinien einhält und Standardstatuscodes für Fehler zurückgibt. Wenn notwendig werden Authentifizierungsmechanismen wie HTTP-Header, API-Schlüssel, OAuth oder JSON Web Token (JWT) implementiert und Fehlercodes, Meldungen und Antworten definiert.

Ein weiterer Teil des Entwicklungsprozesses ist die Dokumentation. Während die API erstellt wird, sollten alle getroffenen Entscheidungen in einem für Menschen und Maschinen lesbaren Dokument festgehalten werden. Ein für Menschen lesbares Dokument ist in einer natürlichen, leicht verständlichen Sprache verfasst. Ein maschinenlesbares Dokument sollte einer API-Spezifikation, wie beispielsweise der OpenAPI-Spezifikation, entsprechen. Dadurch wird das Format standardisiert, sodass das Dokument konsistent ist und in zukünftige Systeme integriert werden kann.

Das API-Design kann ein hochgradig iterativer Prozess sein. Insbesondere wenn die APIs sensible Daten offenlegen, ist es wichtig, sie gründlich auf Fehler und Mängel zu testen. Nachdem man etwas erstellt hat, ist es wichtig zu sehen, ob es wie beabsichtigt funktioniert. Ein wichtiger Teil beim Testen von APIs ist das Mocking. Dabei werden Mock-Server mit Beispieldaten erstellt, um zu überprüfen, ob die API mit ihren Endpunkten korrekt kommuniziert und die erwarteten Ergebnisse zurückgibt. 

Mocking kann neben API-Tests durchgeführt werden. API-Tests umfassen Vertragstests, bei denen festgelegt wird, wie eine Anfrage und Antwort aussehen sollten, Unit-Tests, die bestätigen, dass ein einzelnes Endgerät die erwartete Antwort liefert, Lasttests, bei denen geprüft wird, ob die API auch bei hohem Datenverkehr funktioniert und End-to-End-Tests, bei denen überprüft wird, ob Benutzerszenarien, die die Kommunikation mit mehr als einer API beinhalten, erfolgreich sind. Das Testen kann manuell oder durch die Implementierung automatisierter Test-Frameworks erfolgen.

Wenn alles wie vorgesehen funktioniert, kann die API freigegeben und bereitgestellt werden. Zu diesem Zeitpunkt ist es wichtig, dass die API-Dokumentation fertiggestellt ist, damit andere Benutzer und ihre Maschinen diese API ordnungsgemäß in ihre Computernetzwerkumgebung integrieren können. Es ist möglich, dass Benutzer nach der Veröffentlichung der API Probleme damit haben, die die Stakeholder nicht vorhergesehen haben. Es ist hilfreich, bereits vor der Veröffentlichung der API eine Versionsstrategie zu entwickeln. So können die Entwickler die Anwendung aktualisieren, wenn dies klar und konsistent erforderlich ist.

Ein API-First-Ansatz für die Anwendungsentwicklung priorisiert das Design von APIs zu Beginn des Softwareentwicklungsprozesses und erstellt Anwendungen mit Services, die über APIs bereitgestellt werden. Die Idee besteht darin, durch eine frühzeitige Priorisierung des API-Designs wiederverwendbare, sichere, effiziente und benutzerfreundliche APIs zu schaffen, die besser auf die Unternehmensziele abgestimmt sind. Dieser Ansatz steht im Gegensatz zu einem Code-First-Ansatz, bei dem die Code-Logik an erster Stelle steht und die Entwickler APIs erstellen, die später in die Software passen. 

Das API-Design ist der Schlüssel zu einem API-First-Ansatz. Bei API-first sind APIs von zentraler Bedeutung für die Anwendungsentwicklung. Ein gut durchdachtes Design fördert die Entwicklung besser leistender und wertvollerer Anwendungen. 

Solide API-Designpraktiken können auch dazu beitragen, sowohl die Entwicklererfahrung als auch die Endbenutzererfahrung zu verbessern, indem Entwicklungs- und Leistungsprobleme erkannt und behoben werden, bevor sie sich zu größeren Problemen ausweiten.

Die Stakeholder können von Beginn des Entwicklungsprozesses an feststellen, dass alle Apps des Unternehmens integriert sind und gut miteinander funktionieren. Bei erfolgreicher Implementierung ermöglicht ein API-First-Ansatz mit umfassender Dokumentation Entwicklern die Wiederverwendung vorhandener APIs, anstatt bereits vorhandene Funktionen neu zu erstellen.

REST-APIs (oder RESTful-APIs) sind locker strukturiert. Die einzige Voraussetzung ist, dass sie den folgenden sechs REST-Designprinzipien entsprechen, die auch als architektonische Einschränkungen bezeichnet werden: einheitliche Schnittstelle, Client/Server-Entkopplung, Statuslosigkeit, Cachefähigkeit, mehrschichtige Systemarchitektur und (optional) Code nach Bedarf. 

Durch diese architektonischen Einschränkungen eignen sich RESTful-APIs gut für einen API-First-Ansatz: Insbesondere Client/Server-Entkopplung und Statuslosigkeit sind hilfreich. 

In einer RESTful-API müssen Client- und Serveranwendungen unabhängig voneinander sein. Die einzige Information, die die Client-Anwendung kennen sollte, ist die URI (Uniform Resource Identifier) der angeforderten Ressource; sie kann nicht auf andere Weise mit der Server-Anwendung interagieren. 

RESTful-APIs sind außerdem statusunabhängig, was bedeutet, dass jede Anfrage alle Informationen enthalten muss, die für ihre Bearbeitung notwendig sind. Mit anderen Worten: REST-APIs erfordern keine serverseitigen Sitzungen. Diese Einschränkungen machen diese APIs unabhängig von den Servern eines Unternehmens und machen sie flexibel – client- und serverseitige Anwendungen können mit verschiedenen Sprachen und Protokollen geschrieben werden, ohne das API-Design zu beeinträchtigen.

RESTful-APIs eignen sich ebenfalls gut für eine API-First-Umgebung, da sie skalierbar und schlank sind. Die Trennung zwischen Client und Server verbessert die Skalierbarkeit, da RESTful-APIs keine Informationen zu früheren Clientanforderungen aufbewahren müssen, wodurch Kommunikationsengpässe reduziert werden. Effektives Caching kann auch die Interaktionen zwischen Client und Server reduzieren – ein weiterer Pluspunkt für die Skalierbarkeit. Da RESTful-APIs das HTTP-Format für den Nachrichtentransport verwenden, können sie Datenübertragungen in mehreren Formaten akzeptieren. Dies kann die Integration in neue Umgebungen vereinfachen.

Eine Microservice-Architektur ist ein cloudnativer architektonischer Ansatz, bei dem eine Anwendung aus vielen lose gekoppelten und unabhängig voneinander einsetzbaren kleineren Komponenten oder Diensten besteht. REST-APIs werden oft verwendet, um die Kommunikation zwischen diesen kleineren Diensten zu ermöglichen.

Ein API-First-Ansatz fügt sich gut in das Microservices-Architekturschema ein, da APIs verwendet werden, um die Dienste miteinander zu verbinden. Wenn das API-Design innerhalb eines Unternehmens Priorität hat und die APIs so konzipiert sind, dass sie nahtlos miteinander kommunizieren, sparen die Entwickler Zeit, während sie diese Dienste in größeren Anwendungen zusammenfassen. 

Um den größten Nutzen aus Unternehmens-APIs zu ziehen, legen Unternehmen häufig Wert auf folgende Aspekte:

• API-Governance und Dokumentation
• Sammeln von Stakeholder-Feedback
• Richtige Authentifizierung
• Versionierung
• Standardisierung von Fehlermeldungen
• Skalierung und Kontext
• Konsistenz

Diese Grundsätze tragen dazu bei, dass alle Stakeholder während des gesamten API-Designprozesses auf dem Laufenden bleiben und sicherstellen, dass die APIs mit den Zielen und der Strategie des Unternehmens übereinstimmen.  

API-Governance und Dokumentation: Die frühzeitige Festlegung einer unternehmensweiten API-Governance- und Dokumentationsstrategie trägt dazu bei, die Konsistenz zu fördern und die Navigation im API-Portfolio eines Unternehmens zu erleichtern. Ein Unternehmen könnte sich beispielsweise für die Einführung einer Spezifikation wie OpenAPI entscheiden, damit alle Unternehmens-APIs einem branchenweiten Standard entsprechen. In jedem Fall ermöglicht die Aufrechterhaltung einer ordnungsgemäßen und einheitlichen Governance und Dokumentation neuen API-Nutzern ein schnelles Verständnis der API und ihrer Funktionen. 

Einholen von Feedback der Stakeholder: Frühzeitige Rückmeldungen von wichtigen Stakeholdern und API-Nutzern helfen den Entwicklern, während des gesamten Entwicklungsprozesses auf dem richtigen Weg zu bleiben. Schlechte Kommunikation kann zu Verzögerungen bei der API-Entwicklung und weniger wertvollen APIs führen.

Angemessene Authentifizierung und API-Sicherheit: Um APIs und sensible Daten zu schützen, implementieren Unternehmen Authentifizierungstechniken, die eine Validierung für API-Anfragen ermöglichen. Authentifizierungsmechanismen wie API-Schlüssel, OAuth und JSON Web Tokens (JWT) bieten verschiedene Methoden zur Sicherung von Daten und API-Datenverkehr. Die API-Verschlüsselung, der Prozess der Codierung von Daten für die Übertragung zwischen Client und Server, wird ebenfalls zum Schutz von Daten und APIs verwendet.

Testen und Versionierung: API-Tests umfassen die Abdeckung verschiedener Szenarien, positiver und negativer, um Probleme zu identifizieren, bevor eine API bereitgestellt wird. APIs entwickeln sich im Laufe dieser Tests weiter und Entwickler erstellen neue Versionen, die Fixes beheben oder die Leistung verbessern. Neue API-Versionen werden auch aus anderen Gründen veröffentlicht, z. B. wenn Entwickler einer API neue Funktionen hinzufügen. Versionierung ist die Art und Weise, wie Entwickler Änderungen an einer API verwalten, Änderungen transparent machen und dafür sorgen, dass Updates aktuelle Benutzer nicht stören.

Es ist hilfreich, Versionsmechanismen – wie z. B. URL-basierte Versionierung oder Header-basierte Versionierung – zu definieren, bevor die Entwicklung ernsthaft beginnt. 

Standardisierung von Fehlermeldungen: Eine ordnungsgemäße Fehlerbehandlung verbessert die Erfahrung eines API-Konsumenten, da sie bei der Fehlerbehebung hilft, wenn etwas schiefläuft. Fehlercodes, Meldungen und Antworten müssen die Art des Fehlers genau beschreiben und klar und einheitlich bleiben.

Kontext und Einschränkungen: Jede API existiert in einem bestimmten Kontext, der bestimmt, wie sie aufgebaut wird und welche Funktionen sie hat. Konkurrierende Projekttermine, erwartetes Traffic-Volumen und die Frage, ob das Unternehmen API-First oder Code-First ist, können die resultierende API beeinflussen. Es ist wichtig, dass alle Stakeholder diese Informationen kennen, damit sie während des Entwicklungsprozesses fundierte Entscheidungen treffen können.

Konsistenz: Vor allem die Konsistenz führt im Allgemeinen zu einem besseren API-Design. Konsistenz im API-Design bedeutet mehr als nur Versionierung und Fehlercodes. Bei der Definition von Endgeräten können einheitliche Namenskonventionen die Identifizierung erleichtern. Wenn Sie eine spezifische Anfrage an eine API stellen, sollte diese jedes Mal auf die gleiche Weise gelöst werden. Wenn in einer API-Landschaft alles einheitlich ist, ist es auch einfacher, APIs so zu dokumentieren, dass sie für zukünftige Benutzer verständlich sind.