Wie entwirft man die Adressen einer API?
Eine REST-API (REST steht für Representational State Transfer) gibt jeder Sache eine eigene Webadresse. Die HTTP-Methode sagt, was damit geschehen soll. Gut entworfene Adressen sind so klar, dass andere Entwickelnde sie erraten, ohne die Dokumentation zu öffnen.
Denken Sie an eine Hochschulbibliothek: Bücher, Mitglieder und Ausleihen sind drei Sachen mit je einer Adresse.
Am Ende dieser Lektion
Notiz
Ich kann Adressen für Ressourcen entwerfen und die passende HTTP-Methode wählen.
Schlüsselwörter
| Begriff | Was er bedeutet | Beispiel |
|---|---|---|
| Ressource | eine Sache, die eine API verwaltet | ein Buch |
| Sammlung | alle Ressourcen einer Art unter einer Adresse | /buecher |
| Sicher | eine Methode, die nichts verändert | |
| Idempotent | zweimal gesendet wirkt sie wie einmal gesendet | |
| PUT | ersetzt eine Ressource ganz durch die gesendete | |
| PATCH | ändert nur die gesendeten Felder |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Eine Adresse nennt eine Sache, kein Tun
Schreiben Sie in die Adresse ein Hauptwort im Plural, nie ein Verb. /buecher ist die Sammlung aller Bücher. /buecher/7 ist das einzelne Buch mit der Nummer 7.
Das Verb liefert die Methode. /buchLoeschen ist eine schlechte Adresse. DELETE /buecher/7 sagt dasselbe klar.
Ein Beispiel: schlechte und gute Adressen
| Schlechte Adresse | Besser | Warum |
|---|---|---|
| /getBuecher | GET /buecher | Das Verb steht in der Methode |
| /buchLoeschen?id=7 | DELETE /buecher/7 | Die Adresse nennt nur die Sache |
| /mitgliedNeu | POST /mitglieder | Eine Sammlung legt neue Einträge an |
| /ausleihenVonMitglied/3 | GET /mitglieder/3/ausleihen | Was zu einer Sache gehört, steht unter ihr |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Die Methode sagt, was geschehen soll
GET liest. POST legt etwas Neues an. PUT ersetzt eine Ressource ganz. PATCH ändert einzelne Felder. DELETE entfernt.
Zwei Eigenschaften helfen bei der Wahl. Sicher heißt: Die Methode verändert nichts. Idempotent heißt: Zweimal gesendet wirkt sie wie einmal gesendet. Das zählt, wenn eine Anfrage wegen eines Netzfehlers wiederholt wird.
Ein Beispiel: die fünf Methoden im Vergleich
| Methode | Aufgabe | Sicher | Idempotent |
|---|---|---|---|
| GET | Liest eine Ressource oder eine Sammlung | Ja | Ja |
| POST | Legt eine neue Ressource an | Nein | Nein |
| PUT | Ersetzt eine Ressource ganz | Nein | Ja |
| PATCH | Ändert einzelne Felder | Nein | Meist |
| DELETE | Entfernt eine Ressource | Nein | Ja |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Ein häufiger Fehler
Warnung
Viele glauben, ein Wiederholen sei immer harmlos. Bei GET und DELETE stimmt das. Ein zweites POST legt aber eine zweite Ressource an. Ein Bezahlformular, das zweimal sendet, bucht dann zweimal. Prüfen Sie vor dem Wiederholen, ob die Methode idempotent ist.
Diese API schreibt die Nummer als Filter
Das Lab nutzt PostgREST. Es adressiert ein Buch als /buecher?id=eq.1 und nicht als /buecher/1. Auch das ist REST, denn die Regeln sind Leitlinien und kein Gesetz.
Der Run unten zeigt, dass die Schreibweise /buecher/1 hier gar nicht existiert. Danach sehen Sie den Unterschied zwischen POST und DELETE.
psql das Passwort geben
export PGPASSWORD=shopHier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Tabelle buecher anlegen und füllen
psql -h db -U shop -c "drop table if exists buecher cascade; create table buecher (id serial primary key, titel text not null, fach text not null, jahr int not null, exemplare int not null default 1); insert into buecher (titel, fach, jahr, exemplare) values ('Algorithmen kompakt', 'Informatik', 2019, 3), ('Netze verstehen', 'Informatik', 2021, 2), ('Statistik fuer alle', 'Mathematik', 2018, 1), ('Schreiben im Studium', 'Sprache', 2020, 4); notify pgrst, 'reload schema'"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Adresse /buecher/1 versuchen
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/buecher/1"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Zweimal dasselbe Buch mit POST senden
for i in 1 2; do curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"titel":"Doppelt","fach":"Test","jahr":2024}' "http://api:3000/buecher"; doneHier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Bücher mit dem Titel Doppelt zählen
psql -h db -U shop -t -A -c "select count(*) from buecher where titel = 'Doppelt'"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Zweimal mit DELETE löschen
for i in 1 2; do curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/buecher?titel=eq.Doppelt"; doneHier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Noch einmal zählen
psql -h db -U shop -t -A -c "select count(*) from buecher where titel = 'Doppelt'"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.