Application Programming Interface (API)

Was ist eine API

Eine API (Application Programming Interface) ist eine Schnittstelle, die es ermöglicht, dass verschiedene Softwareanwendungen miteinander kommunizieren und Daten austauschen können, indem sie vordefinierte Regeln und Protokolle verwenden.

Beispiel zur Funktionsweise

Der Gast, der in ein Restaurant geht, ist wie ein Benutzer, der eine Anfrage an eine API stellt. Der Kellner ist die API. Er nimmt die Bestellung (Request) des Gastes entgegen und bringt sie zur Küche. Die Küche ist das Backend-System, das die Bestellung verarbeitet und die gewünschte Speise zubereitet. Der Kellner bringt die fertige Speise (Response) zurück zum Gast.

Technische Details

HTTP-Methoden

Diese Methoden sind die grundlegenden Werkzeuge, mit denen du über eine API mit einem Server kommunizierst. Sie sind wie die verschiedenen Aktionen, die du im Restaurant ausführen kannst, um sicherzustellen, dass du genau das bekommst, was du möchtest.

GET-Methode

• Beispiel: Stell dir vor, du gehst ins Restaurant und möchtest die Speisekarte sehen. Du fragst den Kellner nach der Karte.
• API-Entsprechung: Ein GET-Request wird verwendet, um Daten vom Server abzurufen. Du fragst also die API nach Informationen, ohne etwas zu verändern. Die API gibt dir die angeforderten Daten zurück, ähnlich wie der Kellner dir die Speisekarte bringt.

POST-Methode

• Beispiel: Du hast dich entschieden und gibst dem Kellner deine Bestellung. Du teilst ihm mit, was du essen möchtest.
• API-Entsprechung: Mit einem POST-Request sendest du neue Daten an den Server. Du erstellst also einen neuen Eintrag oder eine neue Ressource. Der Server verarbeitet die Bestellung und gibt dir eine Bestätigung zurück, dass die Bestellung angenommen wurde.

PUT-Methode

• Beispiel: Du merkst, dass du doch lieber einen anderen Nachtisch möchtest und sagst dem Kellner, dass du deine Bestellung ändern willst.
• API-Entsprechung: Ein PUT-Request wird verwendet, um bestehende Daten auf dem Server zu aktualisieren. Du änderst also einen bereits vorhandenen Eintrag. Der Server aktualisiert die Ressource und bestätigt, dass die Änderung erfolgreich war.

DELETE-Methode:

• Beispiel: Du hast es dir anders überlegt und möchtest deine Bestellung komplett stornieren. Du informierst den Kellner, dass du nichts mehr möchtest.
• API-Entsprechung: Mit einem DELETE-Request entfernst du Daten vom Server. Du löschst also eine Ressource. Der Server löscht die angegebene Ressource und bestätigt die Löschung.

Endpunkte

Jeder Endpunkt ist wie ein eigener Koch in der Küche, der spezifische Aufgaben erfüllt. So weiß der Kellner genau, wohin er deine Bestellung bringen muss.

• Beispiel: Stell dir vor, du bist in einem großen Restaurant verschiedenen Arten von Gerichten: Vorspeisen, Hauptgerichte und Desserts. Jedes Gericht hat seinen eigenen Koch, der sich um die Zubereitung der Bestellungen kümmert.
• API-Entsprechung: Ein Endpunkt ist eine spezifische URL, die eine bestimmte Funktion oder Ressource innerhalb einer API repräsentiert. Wenn du eine Anfrage an eine API sendest, richtest du sie an einen bestimmten Endpunkt, der genau weiß, welche Daten oder Funktion er bereitstellen soll.
  • Vorspeisen-Endpunkt: GET /api/v1/gerichte/vorspeisen – Hier kannst du die Liste der verfügbaren Vorspeisen abrufen.

Datenübergabe an einen Endpunkt

• Beispiel: Stell dir vor, du bist im Restaurant und möchtest eine Bestellung aufgeben. Du gibst dem Kellner nicht nur den Namen des Gerichts, sondern auch zusätzliche Informationen, wie „extra scharf“ oder „ohne Zwiebeln“. Der Kellner muss diese Details berücksichtigen, wenn er die Bestellung an die Küche weiterleitet.
• API-Entsprechung: Wenn du Daten an einen Endpunkt übergibst, sendest du nicht nur eine einfache Anfrage, sondern auch zusätzliche Informationen, die der Server benötigt, um die Anfrage korrekt zu verarbeiten. Diese Daten können in verschiedenen Formaten übermittelt werden, etwa als JSON, XML oder Formulardaten.
  • Beispiel: Du möchtest ein Hauptgericht bestellen und gibst dem Kellner die Details deiner Bestellung: POST /api/v1/gerichte/hauptgerichte DATA
  • Die Daten DATA werden als JSON dem Endpunkt übergeben.

Statuscodes

Diese Statuscodes sind wie die Rückmeldungen, die du vom Kellner bekommst, und sie helfen dir zu verstehen, was mit deiner Anfrage passiert ist. Sie sind entscheidend für die Fehlerbehebung und das Verständnis der API-Kommunikation.

• Beispiel: Stell dir vor, du hast dem Kellner deine Bestellung gegeben, und er kommt mit verschiedenen Nachrichten zurück, je nachdem, was passiert ist.
• API-Entsprechung: Statuscodes sind numerische Codes, die in der Antwort der API enthalten sind und den Status der Anfrage beschreiben. Sie helfen dir, zu verstehen, was mit deiner Anfrage passiert ist.
  • 200 OK: Alles ist in Ordnung, deine Bestellung wurde erfolgreich aufgenommen und wird bearbeitet. Es ist der ideale Fall, wenn alles glatt läuft.
  • 404 Not Found: Der Kellner teilt dir mit, dass das Gericht, das du bestellen wolltest, nicht auf der Speisekarte steht. Die API konnte die angeforderte Ressource nicht finden.
  • 500 Internal Server Error: Der Kellner kommt zurück und sagt, dass es ein Problem in der Küche gibt, und dein Gericht nicht zubereitet werden kann. Das sagt aus, dass es ein Problem auf dem Server gibt und die Anfrage nicht korrekt verarbeitet werden konnte.
  • 403 Forbidden: Der Kellner teilt dir mit, dass du dieses Gericht nicht bestellen kannst, da es nur für VIP-Gäste verfügbar ist. Die API verweigert den Zugriff auf die angeforderte Ressource.

Übungen

Ergänze in der Tabelle eigene API-Anfragen. Sie können fiktive Bestellungen sein. Überlege, welche HTTP-Methode und Statuscodes sinnvoll wären.

Anfrage	Met.	Endpunkt	DATA	Statuscode
Ich möchte ein Nudeln bestellen.	POST	/api/v1/gerichte/desserts	{„gericht“: „Pasta“}	404: Es gibt kein Schnitzel auf der Dessertkarte
	POST
	GET	/api/v1/gerichte/vorspeisen
	GET
	PUT		{„gericht“: Pasta“,   „extras“: [„extra scharf“, „extra Zwiebeln“]}
Ich möchte bitte mein Schnitzel mit Kartoffelsalat anstelle von Pommes
	DELETE			500:
	DELETE

Bildquelle: Tierney – stock.adobe.com