Abschnitt 11 · Lektion 1
Was ist eine API?
Ein Programm, das die Bücherliste abholt, kann mit einer HTML-Seite wenig anfangen. Es müsste die
Titel zwischen <li> und </li> heraussuchen. Sobald jemand die Seite umgestaltet, findet es
nichts mehr. Eine API, auf Deutsch Schnittstelle, liefert dieselben Daten ohne Überschrift und ohne
Farbe an ein anderes Programm, und zwar in einer Form, auf die es sich verlassen kann.
Dieselben Daten, zwei Verpackungen
import express from "express";
const app = express();
const buecher = [
{ id: 1, titel: "Node in der Praxis", jahr: 2020 },
{ id: 2, titel: "JavaScript von vorn", jahr: 2019 },
];
// Fuer Menschen: eine Seite, die ein Browser anzeigen kann.
app.get("/buecher", (req, res) => {
const zeilen = buecher.map((buch) => `<li>${buch.titel}</li>`).join("");
res.send(`<h1>Bücher</h1><ul>${zeilen}</ul>`);
});
// Fuer Programme: dieselben Daten, ohne jede Gestaltung.
app.get("/api/buecher", (req, res) => {
res.json({ anzahl: buecher.length, daten: buecher });
});
app.listen(3000); Im Reiter Browser steht die Seite für Menschen. Mit /api/buecher in der Adresszeile stehen dort
dieselben Daten als JSON.
Hinter beiden Adressen steckt dieselbe Liste. Die eine Route baut daraus HTML, die andere gibt sie
als JSON heraus. Der Content-Type sagt dem Empfänger, was er vor sich hat, und danach richtet sich
alles Weitere.
Eine API rendert nichts, und das ist Arbeitsteilung. Wer die Daten bekommt, entscheidet selbst, was daraus wird. Eine Webseite, eine App oder ein Skript, das nachts eine Statistik rechnet. Wer Gestaltung mitschickt, hat diese Entscheidung für alle getroffen, auch für die, die er noch gar nicht kennt.
Dinge statt Tätigkeiten
Am Anfang einer API steht die Wahl der Pfade. Naheliegend ist, sie nach dem zu benennen, was sie
tun. Für eine Notizliste wären das /notizAnlegen, /notizLoeschen, /alleNotizen. Das liest sich
gut und funktioniert auch. Bis die API wächst.
import express from "express";
const app = express();
// Ein Pfad je Taetigkeit. Fuenf Namen, die man kennen muss.
app.get("/alleNotizen", (req, res) => res.json({ anzahl: 2 }));
app.get("/notizLesen", (req, res) => res.json({ id: 1 }));
app.post("/notizAnlegen", (req, res) => res.status(201).json({ id: 3 }));
app.post("/notizAendern", (req, res) => res.json({ id: 1 }));
app.post("/notizLoeschen", (req, res) => res.json({ geloescht: true }));
// Ein Pfad je Ding. Zwei Namen, und die Methode sagt den Rest.
app.get("/notizen", (req, res) => res.json({ anzahl: 2 }));
app.post("/notizen", (req, res) => res.status(201).json({ id: 3 }));
app.get("/notizen/:id", (req, res) => res.json({ id: 1 }));
app.patch("/notizen/:id", (req, res) => res.json({ id: 1 }));
app.delete("/notizen/:id", (req, res) => res.status(204).end());
app.listen(3000); Beide Entwürfe liegen in derselben Datei. Die lesenden Adressen kannst du in der Adresszeile
durchgehen. Die schreibenden schickst du mit curl aus dem Terminal, mit POST oder DELETE
davor.
Beide Reihen tun dasselbe. Oben stehen fünf Pfade, die man einzeln kennen muss. Unten stehen zwei,
/notizen und /notizen/:id, und die Methode sagt, was damit passieren soll. Ein solches Ding
hinter einem Pfad heißt in einer API Ressource (englisch resource), hier die Notizen.
Warum das keine Geschmacksfrage ist
Angenommen, jemand bekommt deine API vorgelegt und will einen Eintrag löschen. Beim ersten Entwurf
muss er raten oder nachschlagen, ob es /notizLoeschen, /loescheNotiz oder /notizEntfernen
heißt. Beim zweiten weiß er es, ohne zu fragen. Es ist derselbe Pfad wie beim Lesen, nur mit
DELETE davor.
Für eine Methode, die ein Pfad nicht kennt, etwa PUT /notizen, gibt es den Statuscode 405 Method
Not Allowed. Der Server aus der Aufgabe zu Lektion 8.5 hat ihn samt Allow von Hand geschickt.
Express schickt ihn nicht von selbst. Im Beispiel kommt auf PUT /notizen ein 404 mit der Zeile
„Cannot PUT /notizen“ zurück, weil keine Route passt. Die APIs in diesem Abschnitt lassen es dabei.
Die Methoden haben außerdem eine Bedeutung, an die sich andere Programme halten. Ein GET gilt als
ungefährlich, und deshalb rufen Suchmaschinen ihn ohne zu fragen auf, genauso wie Browser, die Links
vorab laden. Ist das Löschen als GET /notizLoeschen/1 erreichbar, reicht ein Link darauf. Der
Eintrag ist weg, und niemand hat geklickt.
Mehrzahl, Kennung und Beziehungen
Sammlungen stehen in der Mehrzahl, also /buecher und nicht /buch. Ein einzelner Eintrag hängt
mit seiner Kennung dahinter, also /buecher/2. Für Express ist sie ein Platzhalter im Pfad wie
jeder andere (Lektion 9.3). Und was zu einem Eintrag gehört, wird ein verschachtelter Pfad.
import express from "express";
const app = express();
// Eine Beziehung wird ein verschachtelter Pfad: die Buecher dieses Autors.
app.get("/autoren/:id/buecher", (req, res) => {
res.json({ autor: Number(req.params.id), anzahl: 2 });
});
// Und zwei Faelle, in denen die Regel nicht traegt, weil es kein Ding gibt.
app.get("/suche", (req, res) => {
res.json({ frage: req.query.q, treffer: 1 });
});
app.post("/login", (req, res) => {
res.json({ angemeldet: true });
});
app.listen(3000); Als Erstes antwortet /autoren/3/buecher. Die beiden Ausnahmen sind /suche?q=node und
POST /login.
/autoren/3/buecher liest sich von links nach rechts wie „die Bücher des Autors mit der Nummer 3“.
Mehr steckt hinter verschachtelten Pfaden nicht, und mehr als zwei Ebenen braucht man selten.
Wo die Denkweise aufhört
Die letzten beiden Routen im Beispiel sind keine Dinge. Eine Suche ist eine Frage, und eine
Anmeldung ist ein Vorgang. Beide ließen sich in eine Ressource pressen, und heraus kämen Pfade, die
niemand mehr versteht. /suche und /login sind die besseren Namen.
In der Aufgabe stehen fünf Routen mit Tätigkeitsnamen, und daraus werden zwei Pfade.
Zum Mitnehmen
Eine API liefert Daten ohne Gestaltung an andere Programme. Ihre Pfade heißen nach den Dingen, und die Methode sagt, was mit ihnen geschieht. Nur wo es kein Ding gibt, etwa bei einer Suche, heißt der Pfad nach der Tätigkeit.
Jetzt du
Basis Konto, kostenlosZu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.
Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.
In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.
Was in dieser Lektion steckt
-
Artikel mit 3 Beispielen zum Ausprobieren
Steht hier, ohne Konto lesbar.
-
Aufgabe, dein Code läuft auf einem Server
Öffnet sich mit dem Basis Konto.