REST-APIs für Nichtentwickler erklärt

Was ist eine REST-API?

Wenn du eine App verwendest, stammen viele der auf dem Bildschirm angezeigten Informationen von externen Diensten.

Das Wetter an deinem Reiseziel, der Status einer Lieferung, der Preis eines Produkts, eine Buchung oder das Ergebnis einer Zahlung: Häufig verwaltet die App all diese Daten nicht selbst, sondern ruft sie von anderen Systemen ab.

Hier kommen APIs ins Spiel. Eine API ermöglicht es zwei Softwaresystemen, anhand festgelegter Regeln miteinander zu kommunizieren. Eine REST-API ist eine der gängigsten Möglichkeiten, dies über das Web zu tun. Du kannst sie dir als ein strukturiertes Gespräch zwischen Anwendungen vorstellen:

„Gib mir die Informationen zu diesem Produkt.“

Der Dienst antwortet:

„Hier sind Name, Preis und Verfügbarkeit.“

Oder:

„Erstelle eine neue Buchung für diesen Kunden.“

Der Dienst könnte darauf antworten:

„Buchung erstellt.“

REST steht für Representational State Transfer. Du musst dir diese Abkürzung nicht merken, um zu verstehen, wie das Prinzip funktioniert. Das Grundkonzept ist einfacher: Eine REST-API organisiert Daten als Ressourcen – etwa Benutzer, Produkte, Bestellungen oder Buchungen – und definiert eine standardisierte Methode, um sie zu lesen, zu erstellen, zu ändern oder zu löschen.

Ein konkretes Beispiel

Stell dir eine Reise-App vor, die das Wetter an deinem nächsten Reiseziel anzeigt. Die App muss nicht unbedingt selbst sämtliche Wetterdaten erfassen und aktualisieren. Stattdessen kann sie eine Anfrage an die API eines Wetterdienstes senden.

Der Ablauf sieht so aus:

Deine App → API-Anfrage → Wetterdienst → Antwort → deine App

Die Antwort könnte die Temperatur, Wetterbedingungen und die Vorhersage für die kommenden Tage enthalten. Der Benutzer sieht lediglich das Wetter. Im Hintergrund kommunizieren jedoch zwei Systeme miteinander.

Die Restaurant-Analogie

Eine API lässt sich leicht verstehen, wenn du dir einen Restaurantbesuch vorstellst.

• Du bist die Anwendung, die etwas haben möchte.
• Die Speisekarte beschreibt, was du bestellen kannst.
• Der Kellner übermittelt die Bestellung und bringt die Antwort zurück.
• Die Küche ist der Dienst, der die eigentliche Arbeit erledigt.

Die API übernimmt die Rolle der Speisekarte und des Kellners. Sie zeigt dir, was du anfordern kannst, wie du deine Anfrage formulieren musst und welche Art von Antwort du erwarten kannst. Du musst nicht wissen, wie die Küche arbeitet, um ein Gericht zu bestellen. Ebenso muss eine App nicht unbedingt die interne Implementierung eines Dienstes kennen, um dessen API zu nutzen.

Wie funktioniert eine REST-API-Anfrage?

Jede API-Anfrage enthält einige grundlegende Informationen.

Endpunkt: Wohin wird die Anfrage gesendet?

Der Endpunkt ist die Adresse, an die eine Anfrage gesendet wird. Zum Beispiel:

https://api.example.com/products/42

Diese Adresse könnte für das Produkt mit der ID 42 stehen. Verschiedene Endpunkte können eine Sammlung von Ressourcen, ein einzelnes Element oder eine bestimmte Aktion repräsentieren.

HTTP-Methode: Was möchtest du tun?

Die HTTP-Methode teilt dem Dienst mit, welche Aktion ausgeführt werden soll. Die gängigsten Methoden sind:

• GET → Informationen abrufen;
• POST → eine neue Ressource erstellen;
• PUT oder PATCH → eine vorhandene Ressource ändern;
• DELETE → eine Ressource löschen.

Auf einer Buchungsplattform könnte beispielsweise:

GET /bookings

vorhandene Buchungen abrufen, während:

POST /bookings

eine neue Buchung erstellen könnte. Diese Konventionen sind weit verbreitet, aber keine absolute Garantie. Maßgeblich ist immer die Dokumentation der jeweiligen API.

Header und Body: Zusätzliche Informationen

Die Header enthalten ergänzende Informationen zur Anfrage, beispielsweise das Datenformat oder die für die Authentifizierung verwendeten Zugangsdaten. Der Body enthält dagegen die Daten, die für die Ausführung der Aktion erforderlich sind. Wenn du beispielsweise eine Buchung erstellen möchtest, könnte der Body Folgendes enthalten:

{
  "service": "Consultation",
  "date": "2026-09-15",
  "time": "14:00"
}

Diese Daten werden häufig als JSON dargestellt. Dieses Format ist weit verbreitet, weil es strukturiert und sowohl für Menschen als auch für Software gut lesbar ist.

Was passiert, wenn die Antwort eintrifft?

Nachdem der Dienst die Anfrage erhalten hat, verarbeitet er sie und sendet eine Antwort zurück. Die Antwort enthält normalerweise die angeforderten Daten oder das Ergebnis der Aktion sowie einen HTTP-Statuscode, der angibt, was passiert ist. Die häufigsten Statuscodes lassen sich in drei große Kategorien einteilen.

200–299: Alles in Ordnung

Die Anfrage wurde erfolgreich verarbeitet. Zum Beispiel:

• 200 OK → Anfrage erfolgreich abgeschlossen;
• 201 Created → neue Ressource erstellt.

400–499: Mit der Anfrage stimmt etwas nicht

Das Problem betrifft in der Regel die Anfrage oder die Berechtigungen des Clients. Zum Beispiel:

• 400 Bad Request → ungültige Daten;
• 401 Unauthorized → Authentifizierung fehlt oder ist ungültig;
• 403 Forbidden → der Benutzer verfügt nicht über die erforderlichen Berechtigungen;
• 404 Not Found → die angeforderte Ressource existiert nicht.

500–599: Serverseitiges Problem

Bei dem Dienst, der die Anfrage verarbeiten soll, ist ein Problem aufgetreten. Für Benutzer ist ein Code wie 409 oder 500 allerdings wenig aussagekräftig. Eine gute Anwendung übersetzt den technischen Fehler deshalb in eine verständliche Meldung:

„Dieser Termin ist nicht mehr verfügbar. Wähle bitte eine andere Uhrzeit.“

Das ist wesentlich hilfreicher als:

„HTTP 409 Conflict.“

REST-APIs, Datenbanken, Webhooks und GraphQL: Was ist der Unterschied?

Diese Technologien und Konzepte hängen miteinander zusammen, erfüllen aber unterschiedliche Aufgaben.

REST-APIs und Datenbanken

Eine Datenbank dient zum Speichern von Informationen. Eine API legt dagegen fest, wie andere Systeme mit diesen Informationen interagieren können. Eine Datenbank könnte beispielsweise Folgendes enthalten:

• Benutzer;
• Produkte;
• Bestellungen;
• Buchungen.

Die API kann festlegen, welche dieser Daten gelesen, erstellt oder geändert werden dürfen und wer dazu berechtigt ist. Dadurch entsteht eine Kontrollschicht zwischen der Anwendung und den Daten. Würde ein Browser ohne ausreichende Schutzmaßnahmen direkt mit einer Datenbank verbunden, könnten Informationen oder Aktionen offengelegt werden, die privat bleiben sollten. In Coderblock kann der Agent das Schema einer Postgres-Datenbank im Gespräch entwerfen und anwenden. Standardmäßige Web-Apps verwenden ein eigenes Supabase-Projekt mit Postgres, Auth, Storage und Row Level Security. Im Bereich Backend lassen sich außerdem Tabellen, authentifizierte Benutzer, Storage und Funktionen anzeigen.

REST-APIs und Webhooks

APIs und Webhooks arbeiten in unterschiedliche Richtungen. Bei einer normalen API-Anfrage fragt deine Anwendung aktiv etwas ab:

„War die Zahlung erfolgreich?“

Bei einem Webhook informiert dagegen ein anderer Dienst deine Anwendung selbstständig darüber, dass etwas passiert ist:

„Die Zahlung wurde soeben erfolgreich abgeschlossen.“

Webhooks sind besonders nützlich für Ereignisse, die erst zu einem späteren Zeitpunkt eintreten, beispielsweise Zahlungen, Aktualisierungen von Lieferungen oder Änderungen am Bestellstatus. Sie müssen jedoch überprüft und sicher verarbeitet werden. Im verwalteten Stripe-Ablauf von Coderblock kann die Plattform die Konfiguration des Webhooks übernehmen. Im BYOK-Modus fordert der Agent den geheimen Stripe-Schlüssel sicher an und konfiguriert den Webhook automatisch.

REST und GraphQL

REST und GraphQL sind zwei unterschiedliche Ansätze für die Kommunikation zwischen Anwendungen. Bei REST arbeitest du normalerweise mit mehreren Endpunkten, die verschiedene Ressourcen repräsentieren. GraphQL verwendet dagegen eine Abfrageschnittstelle, über die der Client genau angeben kann, welche Daten er erhalten möchte. GraphQL kann besonders nützlich sein, wenn die Datenanforderungen komplex sind und der Client mehr Kontrolle über die Antwort benötigt. REST ist hingegen sehr weit verbreitet und häufig leichter zu verstehen. Keiner der Ansätze ist jedoch grundsätzlich besser. Die Wahl hängt von der Architektur des Dienstes, den Anforderungen des Produkts, dem Team und der Art des Clients ab, der die Schnittstelle verwenden soll.

Authentifizierung und Autorisierung sind nicht dasselbe

Zwei Begriffe werden häufig verwechselt: Authentifizierung und Autorisierung. Der Unterschied ist einfach. Authentifizierung:

„Wer bist du?“

Autorisierung:

„Was darfst du tun?“

Stell dir eine Plattform mit Kunden und Administratoren vor. Die Anmeldung überprüft, ob du tatsächlich der angegebene Benutzer bist. Das bedeutet jedoch nicht automatisch, dass du alle in der App gespeicherten Daten sehen darfst. Ein Kunde könnte seine eigenen Buchungen sehen. Ein Administrator könnte die Buchungen aller Kunden sehen. Die zugrunde liegende Identität ist dieselbe Art von Information, die Berechtigungen sind jedoch unterschiedlich.

Und was ist mit API-Schlüsseln?

Ein API-Schlüssel identifiziert häufig die Anwendung oder den Dienst, der eine Anfrage stellt. Eine authentifizierte Sitzung kann dagegen den angemeldeten Benutzer identifizieren. Keines von beidem sollte als universeller Freifahrtschein betrachtet werden.

Berechtigungen müssen separat definiert und auch auf Server- oder Datenbankebene durchgesetzt werden. In Coderblock kannst du direkt im Chat anfordern:

„Füge eine Anmeldung und Benutzerkonten hinzu.“

Der Agent kann Supabase Auth, Registrierungs- und Anmeldeseiten, die Sitzungsverwaltung, geschützte Routen und eine mit dem authentifizierten Benutzer verknüpfte Row Level Security konfigurieren. Die Apps enthalten außerdem eine grundlegende Struktur für Profile und Rollen. Du musst daher weder manuell eine Tabelle für Passwörter erstellen noch die Authentifizierungslogik von Grund auf selbst implementieren.

Wo werden API-Schlüssel gespeichert?

Private Zugangsdaten sind ein weiterer wichtiger Punkt. Ein geheimer API-Schlüssel sollte weder im Frontend hinterlegt noch auf GitHub veröffentlicht oder in einem für Benutzer zugänglichen Feld gespeichert werden. Wenn ein Coderblock-Projekt ein Geheimnis benötigt, kann der Agent es über eine sichere Anfrage für Umgebungsvariablen erfassen. Der Wert wird im serverseitigen Secret-Speicher des Projekts aufbewahrt und weder in den Frontend-Code noch in das Gespräch eingefügt.

So planst du eine Funktion, die eine API verwendet

Wenn du eine App mit einem AI-Builder erstellst, musst du nicht bei der Technologie anfangen. Beginne mit dem Ergebnis, das du für den Benutzer erreichen möchtest. „Zeige Kunden den Lieferstatus ihrer Bestellung“ ist eine hilfreichere Anforderung als:

„Füge eine API hinzu.“

Davon ausgehend kannst du festlegen, was benötigt wird.

1. Bestimme die Datenquelle

Welches System enthält die korrekten Informationen? Deine Datenbank? Ein externer Dienst? Stripe? Ein Versandverwaltungssystem? Es muss eine eindeutige Source of Truth geben.

2. Prüfe die Dokumentation

Bevor du einen Dienst integrierst, solltest du Folgendes prüfen:

• verfügbare Endpunkte;
• Authentifizierungsmethode;
• Testumgebungen;
• Nutzungslimits;
• Format der Anfragen und Antworten;
• mögliche Unterstützung für Webhooks.

3. Berücksichtige Fehlerfälle

Was passiert, wenn der externe Dienst langsam ist? Was geschieht, wenn er vorübergehend nicht erreichbar ist? Und was, wenn er unvollständige Daten zurückgibt? Eine gut konzipierte App muss auch dann ein klar definiertes Verhalten zeigen, wenn eine API nicht wie erwartet antwortet.

4. Validiere ein- und ausgehende Daten

Gehe nicht davon aus, dass Daten von einem externen Dienst immer korrekt sind. Sie müssen validiert werden, bevor sie verwendet oder gespeichert werden.

5. Beschränke Berechtigungen

Eine Integration sollte nur die Zugriffsrechte erhalten, die sie tatsächlich benötigt. Wenn ein Dienst Zahlungen lesen muss, bedeutet das nicht automatisch, dass er sie auch ändern darf.

6. Schütze geheime Zugangsdaten

Private Zugangsdaten müssen auf der Serverseite bleiben. Der Browser sollte keinen API-Schlüssel erhalten, mit dem geschützte Aktionen ausgeführt werden können.

7. Teste vor dem Produktivbetrieb

Nutze nach Möglichkeit die Testumgebung des Dienstes. Prüfe nicht nur erfolgreiche Aktionen, sondern auch abgelehnte Anfragen, Fehler, Timeouts, Duplikate und Stornierungen.

8. Vermeide unnötige Aufrufe

Nicht alle Informationen müssen bei jedem Laden einer Seite erneut abgefragt werden. Wenn die Daten es zulassen, kann ein Cache Antwortzeiten, die Anzahl der Aufrufe und die Integrationskosten reduzieren.

Mit APIs in Coderblock arbeiten

In Coderblock werden APIs Teil desselben dialogbasierten Arbeitsablaufs, mit dem du auch den Rest der App erstellst. Du kannst mit einer Idee oder einer Produktvorlage beginnen und die AI bitten, Frontend, Backend und Datenbank zu erstellen.

Wenn du eine Integration hinzufügen möchtest, solltest du das gewünschte Verhalten möglichst genau beschreiben. Zum Beispiel:

„Füge eine Anmeldung für Benutzerkonten hinzu. Jeder Kunde darf nur seine eigenen Buchungen sehen. Wenn der externe Terminplanungsdienst nicht verfügbar ist, zeige eine verständliche Meldung an und ermögliche dem Benutzer, es erneut zu versuchen.“

Eine solche Anforderung beschreibt nicht nur, welche Technologie verwendet werden soll, sondern vor allem, was in der App passieren muss. Der Agent kann die zugrunde liegende Implementierung übernehmen. Du kannst das Ergebnis währenddessen in der Live-Vorschau auf coderblock.dev prüfen und es im Chat weiter verfeinern.

Warum API-Grundlagen auch ohne Programmierkenntnisse nützlich sind

Du musst kein Entwickler sein, um das Konzept einer REST-API zu verstehen. Grundkenntnisse verändern jedoch die Art und Weise, wie du eine App planst. Du verstehst dadurch, warum eine Stripe-Integration etwas anderes ist als die Verbindung mit einer Datenbank, warum sich ein Webhook von einer normalen API-Anfrage unterscheidet und weshalb ein API-Schlüssel niemals im Frontend offengelegt werden sollte. Vor allem helfen sie dir dabei, bessere Anforderungen an die AI zu formulieren.

Anstatt einfach nur Folgendes zu verlangen:

„Füge eine API hinzu.“

kannst du beschreiben, was passieren soll, welche Daten verwendet werden, wer darauf zugreifen darf und wie sich die App bei einem Fehler verhalten soll. Die AI kann einen großen Teil der technischen Komplexität übernehmen.

Je klarer du jedoch das gewünschte Verhalten beschreibst, desto mehr Kontrolle hast du über das Produkt, das du entwickelst.