Anatomie eines API-Aufrufs

Du hast wahrscheinlich schon häufiger von APIs (Application Program Interfaces) gehört. Aber weißt du, was eine API ist, was sie macht und wie sie funktioniert? In diesem Artikel untersuchen wir den Begriff und die unterschiedlichen Aspekte eines API-Aufrufs.

Was ist eine API?

Eine API ist ein Softwareprogramm, das mit einer anderen Software kommuniziert und üblicherweise einen Dienst anbietet. Ein einfaches Beispiel ist eine Anwendung, die bei der Eingabe von Postleitzahlen Informationen zu Stadt und Land ausgibt. Der API-Client (der Nutzer) fragt den Server nach den Informationen, indem er die Postleitzahl als Parameter weitergibt. Der Server akzeptiert die Anfrage und gibt die angeforderten Daten aus.

APIs dienen der Effizienz

Nehmen wir mal an, du hast Kopfschmerzen. Damit die Kopfschmerzen nachlassen, benötigst du ein Schmerzmittel. Du weißt, andere haben ein Schmerzmittel entwickelt, dass dir helfen könnte, du musst jedoch stattdessen deine eigene Version des Medikaments erzeugen. Das macht keinen Sinn. Oder? Warum solltest du Zeit und Mühe für deine eigene Medikamentenversion aufbringen, wenn so viele andere bereits etwas entwickelt haben? Ohne APIs wäre die Softwareentwicklung diesem Beispiel ähnlich.

Das gemeinsame Nutzen oder die Wiederverwendung war in der Softwareentwicklung lange ein Thema. Warum sollte ein Entwickler jedes Mal ein neues Programm für Postleitzahlen entwickeln, wenn die Post ein kostenloses Programm anbietet? Durch Nutzen einer API muss ein Entwickler nicht zusätzlichen Code schreiben oder jedes Mal den Code aktualisieren, wenn eine Änderung am PLZ-System vorgenommen wird. Da der Entwickler den Programmcode nicht schreiben oder pflegen muss, braucht er nur den zu seiner Anwendung gehörenden Code bearbeiten.

API-Implementation

Wie ein Programmierer eine API implementiert, geht niemanden etwas an. Das stimmt. Der Client kümmert sich nicht darum, was nach der Schnittstelle passiert. Wenn du eine Münze in einen Kaugummiautomaten wirfst, interessiert es dich, wie die Maschine das Kaugummi in die Ausgabe befördert? Wahrscheinlich nicht, solang du dein Kaugummi tatsächlich erhältst. Die Programmiersprachen, Datenbanken und Betriebssysteme, die eine API nutzt, sind dem Client nicht wichtig. Das ist das Schöne an einer API. Was wichtig ist, ist die Schnittstelle.

Schütze die Schnittstelle

Die Systeme hinter der Schnittstelle können sich komplett ändern, die Schnittstelle selbst muss jedoch gleich bleiben. Sobald sie freigegeben wurde, achtet der Programmierer darauf, nur noch optionale Parameter zu einer Schnittstelle hinzuzufügen. Änderungen an die erforderlichen Parameter eines API-Aufrufs, „zerstören“ die Schnittstelle. Wenn beispielsweise die Schnittstelle der PLZ-API zuvor eine fünfstellige PLZ erforderte, nun aber zusätzlich die vierstellige Erweiterung verlangt, funktioniert die Schnittstelle aufgrund der Änderung nicht mehr. Aufgrund der Änderung bei der Schnittstelle funktioniert auch jede Anwendung, die sich auf die alte API stützte, nicht mehr. Um dieses Problem zu lösen, hat der API-Anbieter mehrere Möglichkeiten:

• Akzeptieren des vierstelligen Parameters mithilfe eines optionalen Parameters
• Akzeptieren von sowohl fünf- wie auch neunstelligen PLZs und Verarbeitung der Änderungen im Hintergrund
• Erweitern der API, sodass ein neuer Aufruf zur Verarbeitung von neunstelligen PLZs akzeptiert wird und der ursprüngliche API-Aufruf intakt bleibt.

Eins der wichtigsten Tools, die du im Zusammenhang mit APIs haben kannst, ist die API-Dokumentation. Die Dokumentation ist der Schlüssel zum Verständnis der Schnittstelle. Der Anbieter kann eine statische API-Dokumentation (siehe Uptrends‘ statische Dokumentation zur MonitorCheck API) oder eine interaktive Dokumentation in einem Produkt wie Swagger (siehe Uptrends‘ API in Swagger) bereitstellen. Swagger sehen wir uns später noch näher an. Was hier jedoch wichtig ist: Du solltest zunächst mit dem Lesen der API-Dokumentation beginnen, und zweitens, sie sollte immer griffbereit beim Programmieren und bei der Fehlerbehebung bei API-Problemen sein.

API-Typen

Es gibt viele unterschiedliche Typen von APIs, je nach ihrer Bestimmung. Um es zu vereinfachen, unterscheiden wir zwei API-Gruppen: Webservices – und alle anderen.

Alle anderen: Bibliotheken, Frameworks und entfernte APIs

Diese werden auch Quellcode-APIs genannt und Entwickler verwenden sie innerhalb ihres Quellcodes, um verschiedene Routineaufgaben zu erledigen. Zum Beispiel ist eine ODBC (Open Database Connectivity) eine API, die eine Verbindung zwischen der Anwendung und dem Datenbankmanagementsystem errichtet. Die API handhabt die Interaktion zwischen den zwei Systemen, gleich um welchen Datenbanktyp, welches Betriebssystem oder welchen Standort es sich handelt, sofern die Datenbank OBDC-konform ist. (Erfahre mehr zu den verschiedenen API-Typen).

APIs wie API-Bibliotheken und -Frameworks sorgen für eine stabilere Software und Elektronik aus mehreren Gründen:

• Wiederverwendung des Codes wird gefördert.
• Der Entwicklungsprozess wird beschleunigt.
• Das gemeinsame Nutzen von Ressourcen wird ermöglicht. Zum Beispiel erhält eine App auf deinem Telefon mithilfe einer API Zugang zu Ortungsdiensten.

APIs haben das Web und das Internet der Dinge revolutioniert.

Webservice-APIs

Webservices sind APIs, die Aufgaben über das Internet ausführen. Fast jede Interaktion, die du online ausübst, verwendet einen oder mehrere Webservices:

• Reservierungsanfragen
• Verarbeitung einer Kreditkartentransaktion
• Abrufen von aktuellen Produktinformationen aus dem Katalog eines Anbieters
• Upload/Download von Bildern nach/von Social-Media-Seiten
• Routenplanung durch eine Navigations-App

Die Liste ist lang und enthält viele Funktionen, über die wir nie nachdenken. Dazu gehören Statusmeldungen von deinen Smart-Geräten oder die Kontaktaufnahme des Navigationsgeräts deines Fahrzeugs mit Google Maps, um aktuelle Verkehrsbedingungen abzurufen oder hochzuladen, genauso wie das Zugreifen deines Smart-TVs auf die API eines Streaming-Dienstes wie Netflix.

Untersuchung eines Webservice-API-Aufrufs

Meistens nutzen Webservices den Architekturstil REST API (Representational State Transfer Application Program Interface). Ein Webservice, der den REST-API-Stil einsetzt, wird „RESTful“ genannt. REST bestimmt weder die Programmiersprache noch das Betriebssystem. Es definiert vielmehr die Designgrundsätze, denen eine API entsprechen muss, um als RESTful gelten zu können. Erfahre mehr über RESTful APIs. Die folgenden Beispiele nutzen einen RESTful-Architekturstil.

RESTful APIs verwenden HTTP

RESTful APIs kommunizieren genauso wie Webbrowser über HTTP/HTTPS und ein Aufruf an eine API ist einer URL zum Aufrufen einer Webseite sehr ähnlich. Zum Beispiel lautet der Aufruf an die Uptrends API, um die Liste der Checkpoint-Standorte und ihre IP-Adressen zu erhalten:

https://api.uptrends.com/v4/Checkpoint

Die URL, um dieselben Daten als eine Webseite anzuzeigen, lautet:

https://www.uptrends.com/checkpoints

Letzteres ruft eine Webseite auf, ersteres eine JavaScript Object Notation (JSON) oder ein XML-Ergebnis.

Die HTTP-Methoden

Die HTTP-Methoden definieren die erforderliche Aktion. Obwohl noch weitere HTTP-Anfragemethoden existieren, konzentrieren wir uns auf fünf der meistgenutzten Methoden.

• GETDie GET-Anfragemethode ruft etwas von einer Ressource ab. Bei unserem Checkpoint-Beispiel kann die API Ergebnisse als Liste aufrufen. Sie könnte jedoch auch eine Datei, einen Status, ein Script oder jede andere digitale Ressource abrufen.
• POSTDie POST-Anfragemethode sendet Daten (und Dateien) an die Ressource. Beispielsweise kann eine POST-Methode eine Ressource zur Ausführung verschiedener Dinge anweisen, etwa das Aktualisieren eines Einkaufskorbs, das Erstellen eines Accounts, das Speichern einer Reservierung oder das Aktualisieren von Social-Media-Kanälen.
• PUTDie PUT-Anfragemethode ähnelt der POST-Methode, indem sie dazu auffordert, die Ressource zu aktualisieren oder zu erstellen. Aber das Replizieren einer POST-Anfrage bewirkt gar nichts, das heißt, sie ist idempotent. Bei einer POST-Anfrage kann die Anfrage zweimal erfolgen, wenn ein Nutzer die Sende-Schaltfläche ein zweites Mal klickt. Durch den Einsatz der PUT-Methode lassen sich doppelte Kundenbestellungen vermeiden. Eine PUT-Methode erfordert, dass eine Anfrage einen URI (Uniform Resource Identifier) enthält, der die zu aktualisierende Ressource eindeutig identifiziert. Wenn die Ressource bereits existiert, werden anhand der PUT-Methode die Änderungen vorgenommen. Existiert die Ressource nicht, erzeugt die PUT-Methode das Objekt mit dem URI.
• PATCHEine PATCH-Methode ist eine Teiländerung oder -aktualisierung einer Ressource. Mit einer PUT- oder POST-Methode kannst du jedes Mal die gesamte Ressource senden. Mit einer PATCH-Methode sendest du jedoch nur die Aktualisierungen.
• DELETEEine DELETE-Methode entfernt eine komplette Ressource. Der Server entscheidet jedoch, wie er die DELETE-Anfrage handhabt und löscht möglicherweise die Ressource nicht wirklich.

HTTP-Anfrage und -Antwort

Wie du nun wahrscheinlich bereits weißt, nutzt ein Client eine HTTP-Anfrage, um etwas vom Server abzufragen. Der Server sendet dies als Antwort zurück. Die Antwort kann Daten enthalten oder nur einen Ergebnis-Code. Sowohl die Anfrage wie auch die Antwort nutzen das folgende Format:

• Request LineDie Request Line (Anfragezeile) des Clients spezifiziert die HTTP-Methode, den Anfrage-URI und die HTTP-Version.Die Antwort enthält ebenfalls eine „Request Line“, aber diese enthält die HTTP-Version und den Antwortcode.
• HeaderHTTP verwendet Header, um zusätzliche Informationen mittels Name-Wert-Paare zu übergeben. Die Anfrage kann viele Header-Zeilen enthalten, wie etwa Host, Datum/Uhrzeit, Verbindungsinformationen, Content-Type-Informationen, Inhaltsgröße und Cache-Einstellungen.
• LeerzeileEine leere Zeile zeigt das Ende des Headers und den Beginn des Nachrichtentextes an.
• NachrichtentextBei GET- und DELETE-Anfragen ist der Nachrichtentext optional, aber für andere Anfragemethoden enthält der Nachrichtentext die Daten (sofern vorhanden), die der Server oder der Client benötigen.

Sehen wir uns einige Beispiele an:

Beispiel-Anfrage

Die folgende Anfrage geht an die Checkpoint-API von Uptrends. Im Code unten siehst du zunächst die Anfragezeile mit der Methode, dem URI und der Protokollversion. Die zweite Zeile, der Host-Header, gibt den Domainnamen des Servers wieder. Die dritte Zeile, der Accept-Header, sagt der API, dass sie mit JSON-Code antworten soll. Die vierte Zeile ist der Autorisierungs-Header, der die codierten Basic-Authentifizierungsdaten enthält.

GET /v4/checkpoint/202 HTTP1.1

Host: api.uptrends.com

Accept: application/json

Authorization: Basic bWjIxOEBNd2ljajb206MRnNjkzNAGFlbEB1cHRyZW5kcy5==

Beispiel-Antwort

In der ersten Zeile der API-Antwort steht die Protokollversion und der Ergebnis-Code. Die Header in der Antwort geben dem Browser Informationen über die Antwort, so etwa, wie lange der Inhalt im Cache verbleiben soll, welcher Art der Inhalt ist, Datum/Uhrzeit und Inhaltslänge. Nach den Headern folgt eine Leerzeile, dann der Inhalt der Nachricht. Der Inhalt der Nachricht enthält JSON-Code (wie in der Anfrage angewiesen), aber XML ist ebenfalls verfügbar.

HTTP/1.1 200 OKaccess-control-expose-headers: Request-Contextcache-control: no-cachecontent-length: 63823content-type: application/jsondate: Thu, 03 Sep 2020 20:41:47 GMTexpires: -1pragma: no-cachereferrer-policy: same-originrequest-context: appId=cid-v1:fa5a4436-5708-4a19-90fb-5e2623304195

{"Data": {"Id": 202,

“Type”: “Checkpoint”,

“Attributes”: {“CheckpointName”: “Aalsmeer”,

“Code”: “AAL1”,

“Ipv4Addresses”: [“213.214.121.213”,

“185.113.196.214”

],”IpV6Addresses”: [{“IpAddress”: “2a02:2858:201:4e::5”,

“IsNative”: true

},{“IpAddress”: “2a02:2858:401:1::214”,

“IsNative”: true

}],”IsPrimaryCheckpoint”: true,

“SupportsIpv6”: true,

“HasHighAvailability”: false

},”Links”: {“Self”: “/Checkpoint/221″

}},”Links”: {“Self”: “/Checkpoint/221”}}

Das obige Beispiel fragt nach Informationen über einen speziellen Checkpoint. Jedoch wurde bei einer vorherigen Anfrage mit einem anderen URI die in diesem Beispiel verwendete Checkpoint ID abgerufen. Einige API-Aufrufe sind eigenständig, aber viele Aufrufe sind Teil einer größeren API-Interaktion.

Tools zum Testen von API-Aufrufen

Es gibt viele kostenlose und kostenpflichtige Tools, mit denen du API-Aufrufe erstellen und testen kannst. Die zwei beliebtesten Tools sind cURL und Swagger UI. Ein weiteres beliebtest Tool, das wir hier aber nicht weiter besprechen werden, ist Postman.

cURL

Das wahrscheinlich meistverwendete Tool ist cURL. Das „c“ steht für Command Line und der URL-Teil für Universal Resource Locator. Mit dem Tool ist es möglich, Daten über die Befehlszeile zu senden und zu empfangen. HTTP ist nur eines der vielen unterstützten Protokolle.

Wahrscheinlich ist cURL bereits auf deinem Computer installiert (wenn du Unix oder einen Mac nutzt, ist das Tool vorinstalliert). Wenn du einen Windows-Rechner nutzt, kannst du mit einem schnellen Test feststellen, ob cURL installiert ist.

• Öffne ein Befehlsfenster (gib „cmd“ in die Suche ein, um die cmd.exe zu finden).
• Gib curl https://www.uptrends.com an der Eingabeaufforderung ein.
• Drücke die Eingabetaste.

Das Ergebnis (siehe Abbildung unten) ist der HTML-Code der Uptrends-Website. Durch Einsatz der cURL-Notation kannst du zu deinen API-Anfragen Header hinzufügen. Erfahre mehr über den Einsatz von cURL und lade es von der offiziellen Website herunter. Du kannst auch das kostenlose E-Book, Everything curl, herunterladen.

Teste API-Aufrufe mit Swagger

Swagger ist ein visuelles Dokumentationstool, mithilfe dessen Entwickler und Nutzer direkt mit deiner API interagieren können, ohne weitere Infrastruktur eingerichtet zu haben. Wenn die von dir gewünschte API über eine OpenAPI Specification verfügt, steht alles bereit. Uptrends bietet eine OpenAPI Specification Einrichtung für Version 4 der API, die du nutzen kannst, wenn du über einen aktiven Uptrends Account verfügst.

Einsatz der OpenAPI Specification von Uptrends

Melde dich mit deinen Uptrends Anmeldedaten an, um Uptrends‘ Swagger-Seite zu nutzen und mit der Uptrends API zu interagieren. Im folgenden Abschnitt zeigen wir dir, wie du einen API-Aufruf mit Swagger ausführst und API-Benutzernamen und -Passwort erhältst.

Zunächst musst du deine API-Anmeldedaten erfahren.

1. Ruf die Uptrends API v4 Swagger Dokumentation auf.
2. Führe einen Bildlauf zu Register durch und klicke, um den Punkt zu erweitern. Du wirst viele andere Aufrufe sehen, aber gehe zunächst weiter bis Register. Du kannst später mit den anderen spielen.
3. Klicke auf den grünen Balken, um die Dokumentation für API-Aufrufe anzuzeigen.
4. Klicke auf Try it out, um die Schaltfläche Execute zugänglich zu machen.
5. Klicke auf Execute.
6. Verwende deine Anmeldedaten von Uptrends, um das Anmeldeformular im Pop-up-Fenster auszufüllen.
   
7. Klicke auf Sign in.
8. Beachte, dass die Werte UserName und Password im Antworttext ausgegeben werden. Diese benötigst du, um die API aufzurufen.
9. Führe einen Bildlauf zum Beginn der Swagger-Webseite aus.
10. Klicke auf die grüne Authorize-Schaltfläche.
11. Verwende den Benutzernamen und das Passwort aus der Antwort, um die Felder auszufüllen (du musst nur den oberen Bereich ausfüllen.)
12. Klicke auf Authorize.
13. Klicke auf Close.

Wenn du nicht angemeldet bist, erhältst du Authentifizierungs-Fehlermeldungen zu deinen API-Aufruf-Versuchen. Spiele etwas mit den verschiedenen API-Aufrufen (Es ist wahrscheinlich erst mal besser, sich an GET-Anfragen zu halten). Beachte die cURL-Syntax, die verwendet wird, um den Aufruf zu erzeugen (siehe Abbildung unten). Swagger behält deine Anmeldedaten mit einem codierten Autorisierungs-Header.

Codierung des Autorisierungs-Headers

Wenn du ein Uptrends API-Nutzer bist und andere Mittel (wie zum Beispiel Skripte) nutzt, um mit der API zu interagieren, musst du eventuell deine API-Anmeldedaten codieren. Um deine Anmeldedaten zu codieren, nutze die base64-Codierung für den Benutzernamen und das Passwort, durch einen Doppelpunkt getrennt.

Der Benutzername und das Passwort

7341223ce90947cda53a66f67481908a:ipbI6+6wUXxlCYSTBUaCuuUyjTQYfNjM

werden

NzM0MTIyM2NlOTA5NDdjZGE1M2E2NmY2NzQ4MTkwOGE6aXBiSTYrNndVWHhsQ1lTVEJVYUN1dVV5alRRWWZOak0=

mit base64-Codierung anhand eines kostenlosen Online-Tools.

Fazit

Wir hoffen, dies hat zum Verständnis von Webservices und ihrer Funktionsweise beigetragen. Wir empfehlen, die Uptrends API weiterhin mit Swagger zu erkunden. Die daraus gewonnen Informationen werden sich bei einer eventuellen Einrichtung eines Multi-Step API Monitorings als praktisch erweisen. Solltest du Fragen zur API haben, empfehlen wir einen Blick in unsere Knowledge Base oder wende dich an unseren superhilfsbereiten Support.