Skip to main content

API Guidance: Ein Überblick über API-Technologien Teil 1

Application Programming Interfaces (APIs) sind ein wesentlicher Bestandteil moderner verteilter Systeme – und ein wesentliches Glied in der Datenlieferkette für moderne, datengesteuerte Organisationen. Sie sind daher unverzichtbar für das Ökosystem des Datenaustauschs, welches das Support Centre for Datasharing fördern möchte. In dieser dreiteiligen Serie, die von eLearning-Modulen begleitet wird, wollen wir konzentriertes und praktisches Wissen für diejenigen anbieten, die über die Entwicklung und den Einsatz einer API nachdenken und daher die Grundlagen dieser Technologie verstehen müssen, sowie für diejenigen, die mehr Informationen darüber suchen, was bei der Implementierung zu beachten ist.

Dieser Inhalt wird auf zwei Arten veröffentlicht:

  1. Hier als Website-Inhalt in drei Episoden, jeden Monat mit einer neuen Folge, und
  2. nach Abschluss der Serie als einzelnes Dokument, das Sie herunterladen und offline lesen können.

Der Leitfaden ist in Englisch, Französisch und Deutsch verfügbar. Auf jede Ausgabe folgen eLearning-Module, die die jeweiligen Themen abdecken und Ihnen helfen, Ihr Wissen zu testen. 

Die Kapitel in der ersten Folge sind:

  • Einführung in APIs
  • Grundlegende API-Konzepte
  • APIs und ihre architektonische Entwicklung

Die zweite Folge umfasst:

  • API-Typen und deren praktische Umsetzung
  • Anwendungsszenarien
  • API-Dokumentation

Wir freuen uns auf Ihre Kommentare und laden Sie dazu ein, weiterführende Themen in unserem forum zu besprechen.

1. Über das Teilen von Daten zwischen Maschinen

Daten können auf viele verschiedene Arten ausgetauscht werden. Wenn Daten digital ausgetauscht werden, ist es wichtig zu verstehen, mit wem sie ausgetauscht werden: zwischen Menschen, zwischen einer Maschine und Menschen – oder nur zwischen Maschinen?

Natürlich stellt der Datenaustausch zwischen Menschen oder zwischen Menschen und Maschinen andere Anforderungen als der Datenaustausch zwischen Maschinen. Menschen können Daten oft unabhängig von ihrer Darstellung gut verstehen. Mitunter ist ein bisschen Training oder Vorwissen hilfreich, aber im Allgemeinen können Menschen Daten in Tabellen, Grafiken, Volltexten und anderen Formaten relativ leicht verstehen. Insbesondere können sie dies häufig tun, obwohl Ihnen der Kontext der Daten unbekannt ist.

Maschinen haben weitaus eingeschränktere Fähigkeiten: Ohne spezielle Anleitung können sie empfangene Daten nicht mit Informationen verbinden, die nicht Teil dieser Daten sind. Ohne vorherige Anweisungen werden sie auch Schwierigkeiten haben, den Kontext zu verstehen oder auch nur Daten zu lesen. Im Prinzip müssen Maschinen daher für jede bestimmte Datendatei, die sie verarbeiten, geschult oder angewiesen werden.

Wenn es um die gemeinsame Nutzung von Daten zwischen Maschinen geht, müssen sich beide Seiten – Client und Server – im Wesentlichen auf einen technischen Vertrag einigen, der die Spezifikationen der Daten sowie die Bedingungen für die gemeinsame Nutzung regelt. Beide Seiten müssen im Voraus wissen, wie die Daten strukturiert sind und welche semantischen Informationen hinter den Daten stehen.

APIs können diese Funktionen bereitstellen und einen nahtlosen Datenaustausch von Maschine zu Maschine ermöglichen. Aus diesem Grund werden sie zunehmend von Anwendern genutzt, die Daten gemeinsam, d.h. mit anderen, nutzen möchten. Leider sind APIs in der Regel keine Tools, die sofort out-of-the-box einsatzbereit sind. Um gut zu funktionieren, müssen sie von sachkundigen Entwicklern mit der gebotenen Sorgfalt geschrieben werden. Dieser Bericht soll die Entwicklung und Verbreitung hochqualitativer APIs erleichtern. Die folgenden Abschnitten geben eine Einführung in webbasierte APIs und die zugrunde liegenden Konzepte.

eLearning Kapitel 1

 

2. Grundlegende Konzepte

Um moderne API-Technologien zu verstehen, ist es wichtig, zuerst einige grundlegende Konzepte zu verstehen. APIs sind ein wichtiges Element zahlreicher moderner verteilter Systeme. Kurz gesagt handelt es sich bei APIs um Schnittstellen zur Standardisierung und Vereinfachung der Interaktion zwischen den verschiedenen Komponenten eines Gesamtsystems, z.B. zwischen verschiedenen Servern. APIs ermöglichen es den Komponenten eines verteilten Systems, Berechnungen über Schnittstellen in einer Client-Server-Beziehung voneinander anzufordern bzw. abzurufen. Bei jedem Abruf ist der anfordernde Dienst der Client, und der Server der Dienst, der ein Programm bereitstellt. Über dieses Grundprinzip hinaus ist es wichtig, auch die Konzepte von HTTP, URL, Datendarstellungsformaten und vordefinierten Kommunikationsmethoden („Remote Procedure Calls“) zu verstehen.

2.1 HTTP

Das „Hypertext Transfer Protocol“ (HTTP) und Weblinks über „Uniform Resource Locators1 (URLs) sind wahrscheinlich die grundlegendsten Konzepte des „Web“. HTTP ist nicht nur für das Surfen im Web wichtig, sondern auch für das Versenden von Nachrichten oder die Übertragung von Daten zwischen mit dem Internet verbundenen Systemen. Damit ist das HTTP die grundlegende Transportschicht für moderne APIs. Es ist ein textbasiertes Protokoll, das vom Menschen leicht gelesen und verstanden werden kann. Darüber hinaus erleichtert es nicht nur die Steuerung einer Kommunikationssitzung, sondern ermöglicht es einem Client und einem Server in einem Anforderungs-/Antwortzyklus Nachrichten auszutauschen, die sowohl Metainformationen in ihren Headern als auch den eigentlichen Nachrichteninhalt (data payload) in ihrem Hauptteil enthalten. Diese Nutzdaten können Daten oder ein ausführbarer Code sein – oder eine Kombination aus beiden.

Die HTTP-Kommunikation kann durch die Verschlüsselung einer Kommunikationssitzung mit einem TLS-Mechanismus (Transport Layer Security) gesichert werden. Heutzutage wird TLS normalerweise in Kombination mit HTTP bereitgestellt und bildet so HTTPS, eine sichere Version von HTTP. HTTPS stellt sicher, dass weder externe noch interne Benutzer eine Kommunikation abfangen können.

2.2 URL

Einfach ausgedrückt ist eine URL eine universelle Form einer Adresse im Web, deren bekanntester Anwendungsfall Websites sind. Im Kontext moderner APIs kann eine URL jedoch auch Einstiegspunkte (access points) und Funktionen eines Servers oder eine (Multimedia-) Ressource adressieren. WS-SOAP und GraphQL sind Beispiele für APIs, die URLs nur zur Adressierung eines Einstiegspunkts verwenden. RESTful-Schnittstellen verwenden stattdessen URLs, die grundlegende Parameter enthalten, um innerhalb einer API definierte Funktionen auszulösen, z.B. das Abrufen bestimmter Daten aus einer Datenbank.

2.3 Datenrepräsentationsformat

Zusätzlich zum Kommunikationsprotokoll, d.h. wie eine Nachricht zwischen zwei oder mehr Eintrittspunkten übertragen wird, ist es auch wichtig zu verstehen, wie der tatsächliche Inhalt einer Nachricht, die Datennutzlast (data payload), dargestellt wird. Für eine relativ einfache Lösung können Benutzer HTML-Formulare für strukturierte Daten, einfachen Text (Base64) oder codierte Daten (Binary Large Object, Blob) bereitstellen. In der Praxis werden jedoch zusätzliche Datendarstellungsformate verwendet, insbesondere für strukturierte Daten:

  • XML (Extensible Markup Language2) ist eine stark typisierte Sprache zur Darstellung strukturierter Daten mithilfe von Tags und Attributen, z.B.:

<message lang="de">Hallo</message>

  • JSON (JavaScript Object Notation3) ist eine einfache Objektnotation, die verschachtelte Klammern und Eigenschaften verwendet, z.B.:

{ "message": { "text": "Hallo", "lang":"de" } }

  • YAML (YAML Ain't Markup Language4) ist eine einfache Objektnotation, die eingerückte Linien und Eigenschaften verwendet, z.B.:

message:

text:Hallo

lang: de

XML wird hauptsächlich vom WS-SOAP-Ansatz verwendet. Das leichtere JSON und YAML werden stattdessen von WS-REST und GraphQL verwendet.

2.4 Vordefinierte Methoden

Das Web ist so konzipiert, dass verschiedene Ressourcen wie Datenelemente, Multimedia-Objekte, Geschäftsobjekte oder einfacher Text einheitlich behandelt werden. Um dieses Prinzip umzusetzen, verfügt das HTTP-Protokoll über vier vordefinierte, agnostische Methoden, die für verschiedene Objekte und Ressourcen verwendet werden können; vorzugsweise sollten diese verwendet werden, um eine API zu definieren:

  • POST, um ein Objekt zu erstellen oder zu posten, z.B. in eine andere Datenbank.
  • GET, um ein Objekt, z.B. aus einer Datenbank, zu lesen.
  • PUT/PATCH, um ein Objekt zu aktualisieren.
  • DELETE, um ein Objekt zu löschen.

eLearning Kapitel 2

 

3. APIs und deren architektonische Evolution

Da Softwaresysteme immer komplexer werden, ändert sich auch ihre Architektur ständig. Die Strukturierung von Software in überschaubare Teile wird daher immer wichtiger. Dieser Abschnitt erläutert, das Zusammenspiel zwischen der architektonischen Entwicklung von Softwaresystemen und APIs.

Die grundlegenden Programmiereinheiten zur Strukturierung von Software sind Module und Bibliotheken. Als sich Softwaresysteme von singulären zu verteilten Systemen entwickelten, kamen lose gekoppelte Komponenten zu dieser Liste hinzu. Die Kommunikation zwischen den verteilten Komponenten wurde über „Remote Procedure Calls“ (RPC) sichergestellt5. Im Wesentlichen ist ein RPC ein Protokoll, mit dem ein Programm „A“ auf einem Computer eine ausführbare Nachricht an ein anderes Programm „B“ senden kann, das sich im selben Netzwerk befinden muss. Auf diese Weise kann das Programm „A“ (der Client) das Programm „B“ (den Server) auffordern, eine bestimmte Dienstleistung (z.B. eine bestimmte Berechnung) bereitzustellen bzw. umzusetzen.

Anfänglich waren RPCs meist auf eine homogene Programmierumgebung und ein bestimmtes Framework beschränkt, z.B. „Java RMI“. Als die Softwaresysteme jedoch immer größer wurden, entwickelten sich die verteilten Komponenten zu unabhängigen Diensten, und das Paradigma der „Serviceorientierten Architektur“ (SOA) wurde populär. Im SOA-Paradigma hat jeder Dienst einen klaren funktionalen Fokus und eine klare Zuständigkeit. Dieser Fokus wurde mit der zweiten Generation von SOA, die oft als „Domain Driven Design"6 (DDD) und „Microservices“ bezeichnet wird, noch deutlicher7. Hier wird die Grenze eines Dienstes in erster Linie durch seine Kerndomäne, genau definierte Schnittstellen (API) und die organisatorische Zuständigkeit durch ein Team definiert, das für einen Dienst vollständig verantwortlich ist.

Entscheidend ist, dass die Entwicklung von Softwaresystemen, die auf einfachen verteilten Komponenten basieren, zu Softwaresystemen, die auf vollständigen Diensten basieren, die Bedeutung von APIs als Konnektoren erheblich erhöht hat. Durch diese Entwicklung wurde auch klar, dass verschiedene Arten von APIs für verschiedene technische Aufgaben benötigt werden.

Gemäß des „Domain Driven Design“ formen ein oder mehrere Microservices eine Domain als „Service". Diese Dienste haben klare Grenzen und können mit den von ihnen verwalteten Daten gebündelt werden. Ein Dienst stellt normalerweise eine oder mehrere APIs für andere Dienste bereit, um mit diesen zusammenzuarbeiten. Es ist auch üblich, dass ein Dienst mit einem Micro-Frontend gebündelt wird, um den Benutzern eine grafische Benutzeroberfläche bereitzustellen. Zusammen wird ein Bündel aus Logik, Daten und Frontend als „in sich geschlossenes System“ (SCS; Self-contained System)8 bezeichnet. Aus organisatorischer Sicht sollte immer nur ein dediziertes Team für ein SCS verantwortlich sein.

Abbildung 1 zeigt eine SCS-Architektur. Sie zeigt in sich geschlossene Systeme als Stapel von Würfeln. Jeder Würfel besteht aus den typischen Architekturebenen: Daten (Data), Geschäftslogik (Ansicht - View) und Front-End. Die Blöcke sind in sich geschlossen, da sie für ihre Funktion nicht auf externe Ressourcen angewiesen sind. Eine Integration aller Systeme zusammen kann als Anwendung angesehen werden, z.B. als Webshop.Abbildung 1:In sich geschlossene Systeme

Abbildung 1: Architektonische Darstellung von Self-Contained Systems

Abbildung 1 zeigt auch, dass Dienste und SCS auf unterschiedliche Weise miteinander kommunizieren können. Beispielsweise kann ein Weblink in der GUI verwendet werden, um Benutzern das Wechseln zu einem neuen Geschäftsvorgang in der Benutzeroberfläche zu ermöglichen, z. B. Anzeigen von Daten, Erstellen eines neuen Elements und vieles mehr. Der klassische Ansatz besteht darin, dass Dienste über RESTful-Schnittstellen synchron miteinander kommunizieren.9 Es kann jedoch auch Fälle geben, in denen ein asynchroner Kommunikationsmodus vorzuziehen ist. Asynchrone Kommunikation bedeutet, dass der Absender einer Abfrage nicht wartet, bis der Empfänger einen Anruf beantwortet hat, z.B. wenn ein System ein anderes System auffordert, bestimmte Daten in seine Datenbank zu schreiben. Anstatt keine weiteren Prozesse zu planen und damit die CPUs zu blockieren, bis eine Antwort empfangen wird (z.B. dass die Daten in die Datenbank des empfangenden Systems geschrieben wurden), verarbeitet das Abfragesystem in der asynchronen Kommunikation sofort weitere Anrufe. Insgesamt hilft dieser Ansatz, CPU-Kapazität zu sparen und besser zu verwalten. Er hat aber auch Nachteile, z.B. langsamere Antwortzeiten wenn eine Antwort zu einer Abfrage eingeht. In der Regel macht dies die synchrone Kommunikation für Benutzer attraktiv, die beispielsweise ein zuverlässiges, schnell verfügbares Lesen von Daten aus einer anderen Datenbank benötigen. Dies kann bei Echtzeitdaten wichtig sein, beispielsweise bei kontinuierlichen Wetteraktualisierungen.

Unabhängig von ihrer technischen Leistung ist es entscheidend, dass API-Schnittstellen genau definiert sind, um wartbare und wiederverwendbare Teile eines komplexen Ökosystems zu erhalten. Dies bedeutet, dass eine API:

  • über eine umfassende formale Spezifikation sowie eine umfassende Dokumentation, die vollständig, verständlich, konsistent und korrekt ist, verfügt.
  • über einen vollständigen Satz schriftlicher verbindlicher Anforderungen verfügt, die eindeutig sind und den Benutzer nicht im Zweifel über ihre Bedeutung lassen.

Als Computer und Softwaresysteme aufkamen, existierten nur wenige Programmiersprachen und Laufzeitumgebungen. Heute sind diese Umgebungen weitaus komplexer geworden. Einer der Haupttreiber für diese Entwicklung ist das Dogma, dass das beste Werkzeug bzw. Tool zur Lösung eines Problems verwendet werden sollte. Dies führte zu einer Vielzahl von Werkzeugen und Programmiersprachen – und bedeutete, dass Programmierer Wege finden musste, damit Anwendungen polyglott wurden, d.h. mit mehreren Sprachen gleichzeitig umzugehen können.

Was bedeutet dies für die Definition und Implementierung einer API? Hervorzuheben ist, dass eine API effektiv eine Schnittstelle ist, die die Übertragung von Daten zwischen mehreren Systemen oder Diensten unterstützt, unabhängig der von diesen Systemen verwendeten Programmiersprachen. Daher sollte die Interoperabilität, d.h. die Fähigkeit, mit einer Vielzahl von Systemen und Programmiersprachen zusammenzuarbeiten, immer einen hohen Stellenwert haben. In der Praxis bedeutet dies, dass gut konzipierte APIs sicherstellen sollten, dass Systeme, die an der Datenübertragung beteiligt sind, unterschiedliche Programmiersprachen verwenden können. Dies kann am besten erreicht werden, indem APIs mit einer neutralen Schemadefinitionssprache programmiert werden, z.B. WSDL (Web Service Description Language10) für WS-SOAP-basierte APIs.

Obwohl dieser Ansatz zweifellos vorzuziehen und dogmatisch überlegen ist, ist er auch mit praktischen Schwierigkeiten befrachtet. In der Praxis werden die meisten APIs nicht nach dem Ansatz „API first“ definiert, bei dem APIs agnostisch entworfen werden. Leider werden Spezifikationen und Dokumentationen häufig aus dem Quellcode des Frameworks abgeleitet, der von dem Dienst oder System verwendet wird, mit dem die API verknüpft ist, z.B. eine Java-Klassendefinition. Zunächst kann dies eine schnelle und bequeme Lösung sein, um geeignete APIs für das Ursprungssystem zu definieren. Letztendlich bedeutet dies jedoch, dass diese APIs programmiersprachen- und Framework-spezifisch sind – und häufig schlecht dokumentiert sind.

Infolge dieses wenig befriedigenden Status quo besteht eine starke Nachfrage nach einem „API first“11Ansatz. Die Annahme ist, dass dieser Entwicklern hilft, APIs einfacher und zielgenauer zu verwenden. Das Befolgen des Ansatzes „API first“ bedeutet, dass die API zuerst mit Hilfe einer umfangreichen Schemadefinitionssprache und -spezifikationen wie OpenAPI erstellt und dokumentiert werden sollte,12 um den erforderlichen Code (in der bevorzugten Sprache) zu generieren und eine umfassende Dokumentation zu schreiben. Die Annahme ist, dass das Befolgen dieses Prinzips letztendlich dazu beitragen wird, interoperablere und damit bessere APIs zu erstellen.

eLearning Kapital 3

 

Bleiben Sie auf dem Laufenden und vergessen Sie nicht, die Materialien zu besprechen, indem Sie jede Folge kommentieren oder mit Ihren Kollegen in unserem forum darüber reden. Testen Sie Ihr Wissen auch in den eLearning-Modulen der SCDS API Guidance: https://elearningcourses.eudatasharing.eu/de/apiguidance/#/

API Guidance - Ein Überblick über API-Technologien Teil 1
Image credit:
Support Centre for Data Sharing