Was ist die Rest-API – Schritt für Schritt mit Beispielen

Möchten Sie eine REST API erstellen, finden aber nur abstrakte Theorie zu „Zustandsübertragung“ und „Protokollen“? Lasst uns das ändern. Dieser Artikel ist ein praktisches Tutorial. Lassen Sie uns auf Papier eine echte [REST-API] für einen Task-Manager (To-Do-Liste) entwerfen.

Am Ende dieses Leitfadens werden Sie genau verstehen, wie Sie URLs strukturieren, die richtigen HTTP-Verben verwenden und professionelle JSON-Antworten entwerfen.

Das Szenario

Erstellen wir eine API zum Verwalten von Aufgaben. Eine Aufgabe hat: id, titulo, descricao und concluida (wahr/falsch).

Schritt 1: Ressourcen (Substantive) definieren

Bei REST denken wir an „Ressourcen“. Die Hauptressource hier ist die Aufgabe. URLs (Endpunkte) müssen diese Ressourcen mithilfe von Substantiven im Plural darstellen.

✅ Rechts: /tarefas
❌ Falsch: /pegarTarefas, /criarNovaTarefa

Die URL gibt an, WAS Sie manipulieren. Das HTTP-Verb identifiziert DIE AKTION.

Schritt 2: Auflisten und erstellen (die Sammlung)

Wie interagieren wir mit der vollständigen Aufgabenliste?

Alle Aufgaben auflisten

Anfrage: GET /tarefas
Bedeutung: „Hey Server, gib mir die vollständige Liste.“
Antwort (200 OK):

[
  { "id": 1, "titulo": "Comprar leite", "concluida": false },
  { "id": 2, "titulo": "Lavar o carro", "concluida": true }
]

Erstellen Sie eine neue Aufgabe

Anforderung: POST /tarefas
Text gesendet:

{ "titulo": "Estudar REST", "descricao": "Ler o tutorial completo" }

Bedeutung: „Hey Server, füge das zur Sammlung hinzu.“
Antwort (201 erstellt): Der Server muss das erstellte Objekt zurückgeben, jetzt mit der generierten ID.

{ "id": 3, "titulo": "Estudar REST", "descricao": "Ler o tutorial completo", "concluida": false }

Schritt 3: Umgang mit einem bestimmten Artikel

Jetzt wollen wir die ID 3-Aufgabe ändern.

Eine bestimmte Aufgabe lesen

Anforderung: GET /tarefas/3
Antwort (200 OK): Gibt nur das Objekt aus Aufgabe 3 zurück.
Was ist, wenn es nicht existiert?: Antwort 404 Nicht gefunden. (Es ist sehr wichtig, den richtigen Fehlercode zu verwenden!).

Eine Aufgabe aktualisieren (Vollversion)

Anforderung: PUT /tarefas/3
Textkörper:

{ "titulo": "Estudar API REST", "descricao": "Atualizado", "concluida": true }

Hinweis: PUT ersetzt normalerweise das gesamte Objekt. Wenn Sie nur den Titel senden, wird der Rest möglicherweise gelöscht (das hängt von der Implementierung ab, aber das ist die PUT-Regel).

Teilweise aktualisiert (PATCH)

Um nur den Status auf „Abgeschlossen“ zu ändern, ohne den Titel erneut zu senden.

Anforderung: PATCH /tarefas/3
Körper: { "concluida": true }
Bedeutung: „Nur dieses Feld ändern“.

Eine Aufgabe löschen

Anforderung: DELETE /tarefas/3
Antwort (204 Kein Inhalt): Erfolgreich, hat aber nichts vorzuweisen.

Schritt 4: Filterung und Paginierung

Was wäre, wenn wir 10.000 Aufgaben hätten? GET /tarefas würde die App zum Absturz bringen. Wir verwenden Abfrageparameter (das Ding nach ?) zum Filtern. Dadurch wird die URL der Ressource nicht geändert, sondern nur deren Ansicht gefiltert.

Paginierung: GET /tarefas?pagina=2&limite=10
Filter: GET /tarefas?concluida=true (Geben Sie mir einfach die ausgefüllten).
Suche: GET /tarefas?busca=leite

HTTP-Statuscodes (Feedback)

Eine RESTful-API muss HTTP-Codes verwenden, um Ihnen mitzuteilen, was passiert ist. Geben Sie in JSON nicht immer 200 mit {"erro": "deu ruim"} zurück. Dadurch werden Überwachungstools kaputt gemacht.

200 OK: Es hat funktioniert.
201 Erstellt: Ich habe die Ressource erfolgreich erstellt (im POST verwendet).
204 Kein Inhalt: Es hat funktioniert, aber ich habe Ihnen nichts zu zeigen (wird in DELETE verwendet).
400 Bad Request: Sie haben falsche Daten gesendet (z. B. fehlte der Titel).
401 Nicht autorisiert: Wer sind Sie? (Fehlendes Token).
403 Verboten: Ich weiß, wer du bist, aber du darfst dich nicht damit anlegen.
404 Not Found: Ich habe es nicht gefunden.
500 Interner Serverfehler: Der Server ist explodiert (Fehler des Backend-Entwicklers).

Fazit

Beim Entwerfen einer REST API geht es um Organisation und Standardisierung. Indem Sie diesem Muster folgen (Substantive in der URL, HTTP-Verben in der Aktion, korrekte Statuscodes), erstellen Sie eine API, die jeder Entwickler auf der Welt intuitiv versteht, ohne ein 500-seitiges Handbuch lesen zu müssen.

Jetzt sind Sie an der Reihe: Nehmen Sie dieses Modell und wenden Sie es auf Ihr nächstes Projekt an!