API ändern, ohne andere zu brechen
Eine API-Dokumentation beschreibt, welche Adressen, Methoden, Felder und Fehlercodes ein Dienst anbietet, und eine Versionsnummer sagt, welcher Stand gemeint ist. Wer eine API ändert, ohne beides zu pflegen, bricht fremde Programme, die sich auf den alten Stand verlassen.
Die Katalog-App der Bibliothek liest das Feld fach. Verschwindet es über Nacht, zeigt die App morgens nichts mehr an.
Am Ende dieser Lektion
Notiz
Ich kann eine API dokumentieren und sie ändern, ohne Nutzende zu brechen.
Schlüsselwörter
| Begriff | Was er bedeutet | Beispiel |
|---|---|---|
| Dokumentation | die Beschreibung dessen, was eine API anbietet | |
| Version | ein benannter Stand der API | v1 |
| Abwärtskompatibel | alte Programme laufen nach der Änderung weiter | |
| Brechende Änderung | eine Änderung, an der alte Programme scheitern | |
| Veralten | etwas ankündigen, das später entfällt | Deprecation |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Die Dokumentation ist das Versprechen an Nutzende
Wer Ihre API nutzt, verlässt sich auf das, was dort steht. Zu jeder Adresse gehören die Methode, die Felder der Anfrage und der Antwort, ein Beispiel, die Fehlercodes und die Regeln für Anmeldung und Limits.
Eine Beschreibung in OpenAPI ist eine Datei, die ein Programm lesen kann. Aus ihr entstehen Webseiten und Prüfungen.
Ein Beispiel: ein Eintrag der Dokumentation
| Angabe | Inhalt |
|---|---|
| Adresse und Methode | GET /buecher |
| Parameter | fach (Text, optional): nur Bücher dieses Fachs |
| Antwort 200 | Liste von Büchern mit id, titel, fach, jahr, exemplare |
| Fehler | 400 bei einem ungültigen Parameter, 429 bei zu vielen Anfragen |
| Anmeldung | Header X-API-Key |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
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 Beschreibung der API abrufen
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Ein neues Feld bricht niemanden, ein fehlendes schon
Eine Änderung ist abwärtskompatibel, wenn alte Programme weiterlaufen. Ein zusätzliches Feld in der Antwort ist es meist, denn niemand liest, was er nicht kennt.
Ein entferntes Feld, ein anderer Typ oder ein neues Pflichtfeld in der Anfrage ist eine brechende Änderung. Alte Programme scheitern daran.
Ein Beispiel: welche Änderung bricht
| Änderung | Bricht sie? | Warum |
|---|---|---|
| Neues Feld in der Antwort | Nein | Alte Programme ignorieren es |
| Feld aus der Antwort entfernt | Ja | Programme, die es lesen, scheitern |
| Feld umbenannt | Ja | Es ist ein Entfernen und ein Hinzufügen |
| Typ eines Feldes geändert | Ja | Aus Zahl wird Text, Rechnungen schlagen fehl |
| Neues Pflichtfeld in der Anfrage | Ja | Alte Anfragen enthalten es nicht |
| Neues optionales Feld in der Anfrage | Nein | Alte Anfragen bleiben gültig |
| Neue Adresse | Nein | Niemand ruft sie bisher auf |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Eine Spalte hinzufügen
psql -h db -U shop -c "alter table buecher add column sprache text default 'de'; 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.
Eine alte Abfrage läuft weiter
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/buecher?select=titel&id=eq.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.
Eine Spalte entfernen
psql -h db -U shop -c "alter table buecher drop column fach; 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.
Dieselbe Art Abfrage scheitert jetzt
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/buecher?select=fach&id=eq.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.
Ein häufiger Fehler
Warnung
Viele glauben, ein neues Feld in der Antwort sei immer harmlos. Meist stimmt das. Ein Programm, das nur bekannte Felder erlaubt, scheitert trotzdem. Schreiben Sie darum in die Dokumentation, dass Nutzende unbekannte Felder ignorieren sollen.
Eine neue Version läuft neben der alten
Muss eine Änderung brechen, bieten Sie eine neue Version an und lassen die alte weiterlaufen. Die Version steht am klarsten im Pfad: /v1/buecher und /v2/buecher.
Kündigen Sie das Ende der alten Version an, nennen Sie ein Datum und geben Sie Nutzenden Zeit zum Wechseln. Erst dann schalten Sie sie ab.
Eine zweite Version als eigene Adresse anlegen
psql -h db -U shop -c "create view buecher_v2 as select id, titel as buchtitel, jahr from buecher; 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 zweite Version lesen
curl -s -w "\n" "http://api:3000/buecher_v2?id=eq.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.