REST-APIs für Anfänger: Ressourcen, Methoden, Statuscodes und Zustandslosigkeit

„REST APIs lernen“ ist ein Ratschlag, den jeder neue Entwickler hört, doch selten wird dabei eine klare Erklärung dafür gegeben, was dieser Ausdruck bedeutet. Die meisten Erklärungen überfluten den Leser mit Fachbegriffen (Verben, Endpunkte, Zustandslosigkeit) oder reduzieren ihn auf „das, was Frontend und Backend verbindet“, was zwar richtig ist, aber keine nützlichen Informationen liefert.

Dieser Leitfaden wählt den Mittelweg. Sie lernen die fünf Grundkonzepte, aus denen fast jede REST API besteht, ein mentales Modell, das Ihnen dabei hilft, sie zu verstehen, wo REST im täglichen Entwicklungsalltag eine Rolle spielt, sowie einen praktischen Ablauf zur Erstellung und Überprüfung Ihrer ersten API mit Node.js und Express – zusammen mit den häufigsten Fehlern, die Anfänger aufhalten.

Kurze Definition

Eine REST API ist eine Reihe von Konventionen, die es zwei Programmen ermöglichen, über das Internet miteinander zu kommunizieren. Am häufigsten handelt es sich dabei um eine Frontend-Anwendung, die vom Backend Daten anfordert oder es bittet, etwas zu speichern. Die Idee erscheint zunächst abstrakt, bis man selbst eine solche API entwickelt – dann wird sie in der Regel schnell verständlich. Deshalb ist REST in der Regel eines der ersten echten Backend-Konzepte, die Menschen lernen, egal ob sie sich auf serverseitige Arbeit spezialisieren oder zu Full-Stack-Entwicklern werden, die beide Seiten der Anwendung bearbeiten.

REST steht für Representational State Transfer, einen architektonischen Stil, der formalisiert wurde, um zu beschreiben, wie das Web selbst funktionieren soll. Um ihn gut nutzen zu können, ist die formale Theorie nicht notwendig; vielmehr basieren alle tatsächlichen REST APIs auf den praktischen Konventionen, die hier beschrieben werden.

Warum REST so viele Anfänger verwirrt

Zwei Faktoren machen dieses Thema schwieriger, als es eigentlich sein sollte.

Das Erste ist der Wortschatzverlust. Im Internet wird „API“ für fast jede Schnittstelle verwendet, die ein Softwareprogramm einem anderen bietet: eine Browser-API, Funktionen einer Bibliothek, ein Cloud-Dienst. REST ist eine spezifische und sehr beliebte Methode zur Erstellung einer Web-API. Da sie so weit verbreitet ist, sagen die Leute oft „API“, wenn sie eigentlich „REST API“ meinen, wodurch Lernende unsicher werden, wo eines der Konzepte endet und das andere beginnt.

Das Zweite ist, dass eine API keine visuelle Oberfläche hat. Ein Button oder ein Layout sind Dinge, die man sehen kann; eine REST-API hingegen nicht. Es ist durchaus möglich, wochenlang Frontend-Projekte zu entwickeln, während man „die API aufrufen“ als Black Box betrachtet. Die Verwirrung tritt in der Regel dann auf, wenn man schließlich selbst eine API erstellen muss und das Konzept plötzlich konkret werden muss.

Die fünf Grundprinzipien hinter jeder REST-API

Beschränkt man sich auf die Grundbegriffe, ist eine REST API eine vereinbarte Methode zum Anfordern und Senden von Daten über HTTP unter Verwendung von URLs sowie einer kleinen Reihe standardisierter Aktionen. Fünf grundlegende Konzepte umfassen fast alles dazu.

Ressourcen und ihre URLs

Eine Ressource ist etwas, das von der API verwaltet wird: Benutzer, Beiträge, Bestellungen, Aufgaben. Jede Ressource oder jede Sammlung von Ressourcen hat ihre eigene Adresse. /users bezieht sich in der Regel auf die Sammlung aller Benutzer, während /orders/42 auf eine bestimmte Bestellung verweist. Ein gutes REST-Design benennt Ressourcen mit Substantiven und lässt die HTTP-Methode die Aktion beschreiben – deshalb sieht man /orders/42 anstelle von /getOrder?id=42.

HTTP-Methoden

Die Methode teilt dem Server mit, was man mit der Ressource vorhat:

• GET liest Daten ohne sie zu ändern.

POST erstellt etwas Neues, in der Regel innerhalb einer Sammlung wie /tasks.

PUT ersetzt eine bereits vorhandene Ressource, während PATCH einen Teil davon aktualisiert.

DELETE löscht sie.

Eine Eigenschaft, die man früh lernen sollte, ist die Idempotenz. Von GET, PUT und DELETE wird erwartet, dass sie idempotent sind: Das Zweimal-Senden derselben Anfrage lässt den Server im selben Zustand wie nach dem Einmal-Senden zurück. POST ist in der Regel nicht idempotent, da zwei identische Anfragen zwei Einträge erstellen können. Dieser Unterschied erklärt viele spätere Entscheidungen bei der API-Entwicklung, beispielsweise warum Wiederholungsversuche für manche Aufrufe sicher und für andere riskant sind.

Anfragen und Antworten

Ein Client sendet eine Anfrage an eine dieser URLs. Die Anfrage enthält die Methode, die URL, Header (Metadaten wie den Inhaltstyp oder ein Autorisierungs-Token) sowie bei Methoden wie POST oder PATCH einen Body. Der Server antwortet mit einer Antwort, die einen Statuscode, Header und in der Regel auch einen Body enthält. In modernen APIs ist dieser Body fast immer JSON.

Statuscodes

Jede Antwort enthält eine dreistellige Zahl, die das Ergebnis zusammenfasst. Für Erfolg sehen Sie 200, bei fehlendem Ressourcen 404 und bei einem Fehler auf dem Server 500. Die erste Stelle gibt an, zu welcher Familie die Zahl gehört: 2xx bedeutet Erfolg, 4xx bedeutet, dass der Client etwas gesendet hat, was der Server nicht akzeptieren kann (fehlerhafter Anfrage, fehlende Authentifizierung, unbekannte Ressource), und 5xx bedeutet, dass beim Server selbst ein Problem aufgetreten ist. Die Familie zuerst zu prüfen, ist der schnellste Weg, um herauszufinden, auf welcher Seite des Systems nachgeforscht werden muss.

Statelessness

Jeder Anfrage muss alles enthalten, was der Server zur Verarbeitung benötigt. Der Server verlässt sich nicht darauf, sich daran zu erinnern, was der Benutzer gerade gefragt hat. Wenn beispielsweise ein Endpunkt eine Authentifizierung des Benutzers erfordert, enthält jede Anfrage die entsprechenden Zugangsdaten, oft einen Token in einem Header. Die Zustandslosigkeit macht REST-APIs skalierbar: Jede Serverinstanz kann jede Anfrage verarbeiten, da keine von ihnen auf privatem Speicher der Konversation angewiesen ist.

Sobald diese fünf Konzepte vertraut erscheinen, liest sich die Dokumentation von REST-APIs meist nicht mehr wie eine Fremdsprache. Jede Referenzseite, auf die man stößt, ist in der Regel nur eine Liste von Ressourcen, den von ihnen unterstützten Methoden, der Struktur der Anfrage- und Antwortkörper sowie den möglichen Statuscodes.

Ein mentales Modell: Bestellen in einem Restaurant

Ein Restaurant ist eine nützliche Analogie. Kunden gehen nicht in die Küche und kochen selbst. Sie lesen die Speisekarte, teilen dem Kellner mit, was sie möchten, und die Küche bereitet das Gericht zu und serviert es.

• Die Speisekarte ist die API-Dokumentation: Sie listet auf, was man anfordern darf.
• Der Kellner ist der Anfragen- und Antwortzyklus, der die Bestellung entgegennimmt und das Ergebnis zurückbringt.
• Die Küche ist der Server, der die Arbeit erledigt, die man nicht direkt sieht.

Wenn man dies auf Methoden überträgt, bedeutet GET, nach dem Inhalt des Menüs zu fragen oder zu überprüfen, was bereits auf Ihrem Tisch liegt. POST dient dazu, eine neue Bestellung aufzugeben. DELETE bedeutet, ein Gericht zurückzuschicken. Sie müssen nicht wissen, wie die Küche intern organisiert ist; es genügt, die Bestellung korrekt aufzugeben, um jedes Mal eine vorhersehbare und konsistente Antwort zu erhalten. Die Analogie hat ihre Grenzen (Restaurants erinnern sich an Ihren Tisch, während eine stateless API das nicht tut), doch sie veranschaulicht die Aufgabenteilung gut.

Wo REST in der praktischen Ingenieurarbeit zum Einsatz kommt

REST ist keine bloße Kuriosität aus Lehrbüchern. Es ist Teil der täglichen Arbeit in fast jedem Produktteam:

• Ein Frontend-Entwickler ruft REST-Endpunkte auf, um ein Profil zu laden, ein Formular abzusenden oder ein Dashboard zu aktualisieren.

Ein Backend-Entwickler entwirft und wartet diese Endpunkte, wobei er entscheidet, welche Daten zurückgegeben werden und in welcher Form.

Ein Full-Stack-Entwickler erledigt beides – manchmal entwirft er einen Endpunkt und nutzt ihn bereits innerhalb derselben Stunde über die Benutzeroberfläche.

Mobile Apps, Integrationen mit Drittanbietern sowie Partnerunternehmen interagieren häufig vollständig über die REST-API eines Produkts, ohne dass dabei eine Benutzeroberfläche zum Einsatz kommt.

Dieser letzte Punkt ist ein Hauptgrund dafür, warum REST zum Standardstil für Web-APIs wurde. Eine sorgfältig entworfene Reihe von Endpunkten kann gleichzeitig Ihren Browser-Client, Ihre iOS- und Android-Apps sowie die Integration externer Partner unterstützen. Eine sorgfältige Gestaltung dieser Endpunkte ist wichtig, denn jeder Client ist letztendlich von ihnen abhängig; unser Artikel zu Fehlern im API-Vertrag, die die Zuverlässigkeit des Frontends beeinträchtigen zeigt auf, was schiefgeht, wenn das nicht der Fall ist.

Warum REST weiterhin der richtige Ausgangspunkt ist

Es existieren auch andere Ansätze. GraphQL und gRPC lösen beispielsweise bestimmte Probleme eleganter als REST – wie zum Beispiel die Möglichkeit für Clients, genau die Felder anzufragen, die sie benötigen, oder effiziente Anrufe zwischen Diensten. Aus drei praktischen Gründen bleibt REST der beste Ausgangspunkt für Anfänger.

Zunächst ist REST überall vorhanden. Die meisten öffentlichen APIs, die Sie wahrscheinlich verwenden werden – von Zahlungsdienstleistern über Wetterdaten bis hin zu sozialen Plattformen – bieten eine REST-Schnittstelle an, oft als Standard. Wenn Sie sie einmal erlernen, erhalten Sie ein mentales Modell, das Sie jedes Mal wiederverwenden können, wenn Sie mit unvertrauter Dokumentation konfrontiert werden.

Zweitens folgt REST dem eigenen Design des Internets. HTTP-Methoden und Statuscodes wurden nicht für REST erfunden; sie sind das Protokoll, das bereits von Browsern und Servern verwendet wird. REST richtig zu erlernen bedeutet, zu verstehen, wie das Internet unabhängig vom verwendeten Framework funktioniert – und dieses Wissen hält länger an als jede spezifische Bibliothek.

Drittens ist es der natürliche nächste Schritt nach den Grundlagen des Frontends. Sobald man sich mit HTML, CSS und JavaScript wohl fühlt, ist in der Regel der Moment gekommen, in dem die Benutzeroberfläche anfängt, echte Daten statt fest programmierten Platzhalter zu laden – genau dann wechselt ein Projekt vom Prototypen zu etwas, das Menschen tatsächlich nutzen können. Für viele Entwickler mit Schwerpunkt Frontend wird es genau zu diesem Zeitpunkt, in dem das Erstellen der eigenen API nicht mehr optional ist und der Weg zur Full-Stack-Entwicklung beginnt. Wenn Sie später die Styles im Detail vergleichen möchten, sehen Sie REST vs GraphQL und die damit verbundenen Kompromisse.

Erste REST-API mit Node.js und Express erstellen

Das Lesen allein bringt bei diesem Thema nur bis zu einem gewissen Punkt weiter. Es wird klar, sobald man etwas gebaut hat – auch wenn es nur etwas Kleines ist. Ein typisches erstes Projekt mit Node.js und Express folgt einer solchen Abfolge:

1. Erstellen Sie einen minimalen Server, der auf einem Port nach eingehenden HTTP-Anfragen lauscht.
2. Fügen Sie eine Route wie /tasks hinzu und verbinden Sie sie mit einem GET-Handler, der eine Liste zurückgibt.
3. Fügen Sie auf derselben Route einen POST-Handler hinzu, der neue Aufgaben entgegennimmt; es reicht in dieser Phase aus, sie in einem einfachen In-Memory-Array zu speichern.
4. Fügen Sie PUT- (oder PATCH)- und DELETE-Handler hinzu, in der Regel unter /tasks/:id, um einzelne Einträge zu aktualisieren und zu löschen.
5. Ersetzen Sie das Array durch eine echte Datenbank, sobald die Struktur der API passend erscheint.
6. Üben Sie jede Route mit einem Tool wie Postman, bevor Sie ein Frontend anschließen.

Zwei Aspekte sorgen dafür, dass diese Vorgehensweise funktioniert. Mit einem Array im Arbeitsspeicher wird die Aufmerksamkeit auf Routen, Methoden und Statuscodes gelenkt statt auf die Einrichtung der Datenbank. Der letzte Schritt, die Routen getrennt voneinander zu testen, ist der, den Anfänger am häufigsten überspringen. Die Überprüfung der API für sich allein, bevor eine Schnittstelle darauf angewiesen ist, macht das Debuggen erheblich einfacher, denn man muss sich nicht mehr fragen, ob ein Fehler in der API oder im aufrufenden Code liegt.

Achten Sie darauf, statt stets 200 angemessene Statuscodes zurückzugeben: 201, wenn eine POST-Anfrage eine Aufgabe erstellt, 404, wenn eine id nicht existiert, 400, wenn im Anfragekörper ein erforderliches Feld fehlt. Genau diese kleinen Entscheidungen machen eine API benutzerfreundlich.

Wo Anfänger in der Regel stecken bleiben

Menschen, die mit REST zu kämpfen haben, mangelt es selten an Fähigkeiten. Sie geraten meist aus vorhersehbaren, behebaren Gründen ins Stocken:

• Das gleichzeitige Erlernen von REST-Konzepten und eines Frameworks wie Express, wodurch nie klar ist, welche Regeln zu HTTP gehören und welche zur Bibliothek.
• Das Nicht-Testen der Routen direkt mit einem Tool wie Postman, wodurch Fehler im Frontend und Backend nicht voneinander unterschieden werden können.
• Die Ignorierung von Statuscodes und Fehlerbehandlung, was zu Verwirrung führt, wenn der Client keinen Unterschied zwischen Erfolg und Misserfolg erkennen kann.
• Das Einstieg in Themen wie Authentifizierung, bevor grundlegende Create-, Read-, Update- und Delete-Routen sicher funktionieren.
• Das exakte Nachbilden der API aus einem Tutorial anstelle des Erstellens einer kleinen Anwendung mit unterschiedlichen Ressourcen, was verdeckt, ob die Konzepte wirklich verstanden wurden.

Das sind Strukturprobleme, keine Talentprobleme. Ihre Behebung ist in der Regel das, was jemanden, der sich wirklich wohl dabei fühlt, Backend-APIs zu entwickeln, von jemandem unterscheidet, der zwar die Fachbegriffe kennt, aber noch nicht in der Lage ist, einen Endpunkt aus einem leeren Dokument zu entwerfen.

Anpassung des Ansatzes an den Ausgangspunkt

Die gleichen Grundprinzipien gelten für alle, doch der Schwerpunkt verschiebt sich je nach Situation.

• Studenten profitieren davon, früh mit REST zu lernen, denn es ist in der Regel das Erste, was aus einem persönlichen Projekt mit einer statischen Seite eine echte Anwendung macht.
• Arbeitsuchende benötigen sowohl die praktischen Fähigkeiten zum Erstellen und Verwenden von APIs als auch die Fähigkeit, diese klar zu erklären, da REST-Fragen in Vorstellungsgesprächen für viele Positionen auftauchen.

Karrierewechselnde finden diese Ideen oft zugänglicher, als erwartet; das Restaurant-Modell stützt sich auf alltägliche Erfahrungen statt auf technisches Wissen.

Frontend-Entwickler lernen häufig REST speziell als Brücke zu Full-Stack-Arbeiten, um ihre Fähigkeiten auszubauen, ohne das zu verlassen, was sie bereits wissen.

Gewohnheiten, die das Verständnis der Konzepte festigen

Einige Gewohnheiten unterscheiden konsequent diejenigen, die REST wirklich verstehen, von denen, die nur die Begriffe kennen.

Bauen Sie etwas Kleines und Originelles, wie eine To-Do-Liste oder eine Notizen-API, anstatt nur Dokumentation zu lesen. Die Konzepte werden nachhaltig, sobald Sie eine kaputte Route debuggen mussten.

Lernen Sie, Fehler zu diagnostizieren, anstatt zu raten. Lesen Sie den Statuscode und die Fehlermeldung, entscheiden Sie, ob das Problem auf der Client- oder Serverseite liegt, und bestätigen Sie dies mit einer direkten Anfrage. Im Berufsalltag ist dieses Instinkt wichtiger als auswendig gelernte Definitionen – und genau das unterscheidet jemanden, der APIs entwickelt hat, von jemandem, der sie nur aufgerufen hat. Wenn Sie weiterkommen wollen, macht das Zurückgeben von Fehlern in einem einheitlichen, dokumentierten Format die Diagnose für alle Nutzer Ihrer API einfacher.

Erhalten Sie schnell Feedback. Die Fähigkeit, einen erfahrenen Entwickler, einen Kollegen oder ein Community-Forum zu fragen, warum eine Anfrage falsche Daten zurückgibt, ist oft der Unterschied zwischen dem Abschluss eines ersten API-Projekts und seinem Aufgeben. Lange Phasen des passiven Videoanschauens ohne dieses Feedbackschleifen sind der Punkt, an dem viele Lernende den Antrieb verlieren.

Häufige Fragen von Anfängern

Was ist eine REST API – in einem Satz?

Es handelt sich um eine Reihe von Konventionen, die es Anwendungen ermöglichen, über das Internet mithilfe standardmäßiger HTTP-Anfragen und vorhersehbarer Antworten zu kommunizieren.

Müssen Frontend-Entwickler REST lernen?

Ja. Die Arbeit am Frontend beinhaltet ständigen Gebrauch von REST-APIs, weshalb in fast allen Fällen ein grundlegendes Verständnis erwartet wird. Es ist außerdem einer der einfachsten Einstiegspunkte, falls man später zum Full-Stack-Entwicklung wechseln möchte.

Ist REST schwer zu lernen?

Die Kernideen sind verständlich, sobald sie klar erklärt werden. Die größte Schwierigkeit ergibt sich meist aus erklärenden Begriffen voller Fachjargon und nicht von den Konzepten selbst.

Ist ein Informatikstudium erforderlich, um Backend-APIs zu entwickeln?

Nein. Viele praktizierende Entwickler, einschließlich Full-Stack-Entwickler, haben durch Bootcamps, Selbststudium oder Mentoring gelernt und nicht über einen formellen Abschluss.

Kann man das lernen, während man einen Vollzeitjob hat?

Ja. Die Konzepte sind kompakt, und ein kleines Projekt, das an ein paar Abenden oder Wochenenden erstellt wird, reicht aus, um sie verständlich zu machen.

Zusammenfassung

REST ist weniger beängstigend, als sein Ruf vermuten lässt. Es handelt sich um eine konsistente Methode, mit der Software Informationen anfordern und senden kann – basierend auf demselben HTTP-Protokoll, das bereits das Internet antreibt – und es bildet die Grundlage für die meisten Apps, die man täglich verwendet.

• Fünf Konzepte spielen die wichtigste Rolle: Ressourcen mit URLs, HTTP-Methoden, Anfragen und Antworten, Statuscodes sowie Statelessness.
• Lernen Sie zunächst die Konzepte, bevor Sie ein Framework verwenden, und nutzen Sie anschließend Express, um sie in die Praxis umzusetzen.
• Testen Sie jede Route einzeln, bevor ein Frontend davon abhängt.
• Betrachten Sie Statuscodes und Fehlerbehandlung als Teil des Designs und nicht als nachträgliche Ergänzung.

Bauen Sie etwas Kleines und Originelles und lernen Sie, Fehler zu diagnostizieren anstatt zu raten.