Abschnitt 11 · Lektion 7
Synthese: die Bücher-API
Jede Route aus diesem Abschnitt stimmt für sich genommen. Ein Aufrufer kann sich aber erst auf die API verlassen, wenn Pfade, Codes, Prüfung und Fehlerform überall gleich sind. Dafür brauchen die Teile einen Aufbau, der sie zusammenhält.
Die API am Stück
import express from "express";
export const router = express.Router();
const notizen = [
{ id: 1, text: "Milch kaufen", wichtig: false },
{ id: 2, text: "Steuer abgeben", wichtig: true },
];
let naechsteId = 3;
function baueFehler(status, code, meldung, felder) {
const fehler = new Error(meldung);
fehler.status = status;
fehler.code = code;
fehler.felder = felder;
return fehler;
}
function pruefe(rumpf = {}) {
const verstoesse = [];
if (typeof rumpf.text !== "string" || rumpf.text.trim() === "") {
verstoesse.push({ feld: "text", meldung: "fehlt oder ist leer" });
}
if (typeof rumpf.wichtig !== "boolean") {
verstoesse.push({ feld: "wichtig", meldung: "fehlt oder ist kein Wahrheitswert" });
}
return verstoesse;
}
router.get("/", (req, res) => {
res.json({ anzahl: notizen.length, daten: notizen });
});
router.get("/:id", (req, res, next) => {
const notiz = notizen.find((eintrag) => eintrag.id === Number(req.params.id));
if (notiz === undefined) {
return next(baueFehler(404, "nicht_gefunden", `Notiz ${req.params.id} gibt es nicht.`));
}
res.json(notiz);
});
router.post("/", (req, res, next) => {
const verstoesse = pruefe(req.body);
if (verstoesse.length > 0) {
return next(baueFehler(400, "ungueltig", "Die Notiz ist unvollständig.", verstoesse));
}
const notiz = { id: naechsteId++, text: req.body.text, wichtig: req.body.wichtig };
notizen.push(notiz);
res.status(201).location(`/api/notizen/${notiz.id}`).json(notiz);
});
router.delete("/:id", (req, res, next) => {
const platz = notizen.findIndex((eintrag) => eintrag.id === Number(req.params.id));
if (platz === -1) {
return next(baueFehler(404, "nicht_gefunden", `Notiz ${req.params.id} gibt es nicht.`));
}
notizen.splice(platz, 1);
res.status(204).end();
}); import express from "express";
import { router as notizenRouter } from "./routen/notizen.js";
const app = express();
app.use(express.json());
app.use("/api/notizen", notizenRouter);
// Standardfall und Fehler-Handler, beide ganz unten und beide in
// derselben Form wie alles andere.
app.use((req, res) => {
res.status(404).json({ fehler: { code: "nicht_gefunden", meldung: "Diese Adresse gibt es nicht." } });
});
app.use((fehler, req, res, next) => {
const status = fehler.status ?? 500;
if (status === 500) {
console.error(fehler.message);
}
res.status(status).json({
fehler: {
code: fehler.code ?? "serverfehler",
meldung: status === 500 ? "Da ist etwas schiefgegangen." : fehler.message,
felder: fehler.felder,
},
});
});
app.listen(3000); Im Reiter Browser steht die Liste unter /api/notizen. Unter /api/notizen/2 findest du eine
einzelne, unter /api/notizen/99 den Fehlerfall und unter /gibtsnicht den Standardfall. Das
POST liegt in der Befehlsleiste.
Die Anwendung steckt in zwei Dateien. Im Router stehen die Routen und alles, was mit Notizen zu tun
hat. In der server.js steht, was für die ganze Anwendung gilt, der Parser, das Einhängen unter
/api/notizen, der Standardfall für unbekannte Pfade und der Fehler-Handler.
Die Aufteilung ist dieselbe wie in Lektion 10.4, und das Präfix steht fast nur an einer Stelle. Im
Router heißen die Pfade / und /:id. Nur die Location-Kopfzeile braucht die volle Adresse, denn
die liest der Aufrufer. Soll die API morgen unter /api/v2/notizen liegen, ändern sich das
Einhängen und diese eine Kopfzeile.
/api/notizen/99 und /gibtsnicht sind zwei völlig verschiedene Fälle, ein unbekanntes Einzelstück
und ein unbekannter Pfad. Trotzdem sieht die Antwort gleich aus. Ins Protokoll schreibt der
Fehler-Handler nur einen 500. Ein 404 oder 400 ist eine Nachricht an den Aufrufer und kein Vorfall
auf der eigenen Seite.
Prüfen mit curl
curl steht seit Abschnitt 8 in den Befehlsleisten. Hier steht es einmal am Stück, mit allem, was
eine API braucht.
import express from "express";
const app = express();
app.use(express.json());
const notizen = [
{ id: 1, text: "Milch kaufen", wichtig: false },
{ id: 2, text: "Steuer abgeben", wichtig: true },
];
let naechsteId = 3;
app.get("/api/notizen/:id", (req, res) => {
const notiz = notizen.find((eintrag) => eintrag.id === Number(req.params.id));
if (notiz === undefined) {
return res.status(404).json({ fehler: { code: "nicht_gefunden", meldung: "Diese Notiz gibt es nicht." } });
}
res.json(notiz);
});
app.post("/api/notizen", (req, res) => {
// Der Standardwert faengt den Fall ab, dass der Rumpf nicht als JSON ankommt
// und req.body deshalb undefined ist. Der letzte curl-Aufruf zeigt ihn.
const rumpf = req.body ?? {};
if (typeof rumpf.text !== "string" || typeof rumpf.wichtig !== "boolean") {
return res.status(400).json({
fehler: { code: "ungueltig", meldung: "Die Notiz braucht text und wichtig." },
});
}
const notiz = { id: naechsteId++, text: rumpf.text, wichtig: rumpf.wichtig };
notizen.push(notiz);
res.status(201).location(`/api/notizen/${notiz.id}`).json(notiz);
});
app.delete("/api/notizen/:id", (req, res) => {
const platz = notizen.findIndex((eintrag) => eintrag.id === Number(req.params.id));
if (platz === -1) {
return res.status(404).json({ fehler: { code: "nicht_gefunden", meldung: "Diese Notiz gibt es nicht." } });
}
notizen.splice(platz, 1);
res.status(204).end();
});
app.listen(3000); import { spawn, execSync } from "node:child_process";
import { setTimeout as warte } from "node:timers/promises";
// Der Server laeuft als eigener Prozess. Muesste er im selben laufen,
// blockierte ihn das synchrone execSync und keine Anfrage kaeme durch.
const kind = spawn("node", ["notizen-server.js"], { stdio: "ignore" });
for (let versuch = 0; versuch < 100; versuch++) {
try {
await fetch("http://127.0.0.1:3000/api/notizen/1");
break;
} catch {
await warte(50);
}
}
const befehle = [
"curl -s -w ' [%{http_code}]' http://localhost:3000/api/notizen/2",
"curl -s -w ' [%{http_code}]' -X POST -H 'Content-Type: application/json' -d '{\"text\":\"Neu\",\"wichtig\":false}' http://localhost:3000/api/notizen",
"curl -s -w ' [%{http_code}]' -X DELETE http://localhost:3000/api/notizen/1",
"curl -s -w ' [%{http_code}]' -X POST -d '{\"text\":\"Ohne Kopfzeile\",\"wichtig\":false}' http://localhost:3000/api/notizen",
];
for (const befehl of befehle) {
// Das Statusanhaengsel steht in jedem Befehl gleich, die Ausgabe laesst
// es deshalb weg. Der Rest steht da, wie man ihn tippen wuerde.
console.log(befehl.replace(" -w ' [%{http_code}]'", ""));
console.log(` ${execSync(befehl).toString()}`);
}
kind.kill(); Für eine API braucht curl vier Angaben. -X setzt die Methode, -H schickt eine Kopfzeile, -d
schickt den Rumpf, und -s schaltet die Fortschrittsanzeige ab, die sonst die Ausgabe zumüllt. Ein
GET braucht nur die Adresse und -s.
Das Anhängsel -w ' [%{http_code}]' schreibt den Statuscode hinter die Antwort. Ohne es steht bei
einem 204 gar nichts da, und man weiß nicht, ob etwas passiert ist. In der Ausgabe des Beispiels
fehlt es, der Rest der Zeile steht da, wie man ihn tippt.
curl liegt auch in dieser Sandbox. Läuft der Server der Aufgabe, kannst du dieselben Aufrufe im
Terminal gegen seine Pfade schicken. Bei
curl -s -w ' [%{http_code}]' http://localhost:3000/api/buecher/1 steht das Buch da und dahinter
[200]. Bei einem -X DELETE auf dieselbe Adresse steht nur [204] da, denn mehr kommt nicht
zurück.
Die Falle im letzten Aufruf
Die beiden POST-Aufrufe im Beispiel schicken einen gleich gebauten Rumpf, und der erste ergibt
201, der zweite 400. Der einzige Unterschied ist die Kopfzeile
-H 'Content-Type: application/json'.
curl -d schickt den Rumpf als Formular (application/x-www-form-urlencoded), wenn man nichts
anderes sagt. Für diesen Typ fühlt sich express.json() nicht zuständig, und req.body bleibt in
Express 5 undefined, wie bei der Prüfung an der Tür in Lektion 11.5. Deshalb steht in beiden
Beispielen der Standardwert {}, einmal als Standardargument von pruefe und einmal hinter ??.
So wird aus dem Absturz mit 500 ein ehrlicher 400.
Nach dem Neustart ist alles weg
import express from "express";
const app = express();
app.use(express.json());
const notizen = [{ id: 1, text: "Milch kaufen", wichtig: false }];
let naechsteId = 2;
app.get("/notizen", (req, res) => res.json({ anzahl: notizen.length }));
app.post("/notizen", (req, res) => {
const notiz = { id: naechsteId++, text: req.body.text, wichtig: req.body.wichtig };
notizen.push(notiz);
res.status(201).location(`/notizen/${notiz.id}`).json(notiz);
});
// Dieser Server beendet sich selbst, denn zweimal-starten.js startet
// ihn als Kindprozess und wartet auf sein Ende.
const server = app.listen(3000, async () => {
await fetch("http://127.0.0.1:3000/notizen", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: "Neu", wichtig: false }),
});
const liste = await (await fetch("http://127.0.0.1:3000/notizen")).json();
console.log(`nach dem Anlegen ${liste.anzahl} Notizen`);
server.close();
}); import { execSync } from "node:child_process";
// Zweimal derselbe Prozess, zweimal von vorn. Nichts von dem, was der
// erste Lauf angelegt hat, ist im zweiten noch da.
for (const lauf of [1, 2]) {
const ausgabe = execSync("node fluechtig.js").toString().trim();
console.log(`Lauf ${lauf}: ${ausgabe}`);
} Der zweite Lauf endet genau wie der erste. Angelegt wird jedes Mal, nur fängt er wieder bei einer Notiz an.
Die Daten liegen in einem Array, und ein Array lebt im Prozess. Solange er läuft, funktioniert alles. Startet er neu, weil sich eine Zeile geändert hat oder weil ein Absturz dazwischenkam, ist der Bestand wieder der vom Programmstart.
An Routen, Prüfung und Fehlerform ändert das nichts. Es fehlt ein Ort, an dem die Daten den Prozess überleben, und den bekommt die Bücher-API in Abschnitt 12 mit einer Datenbank.
In der Aufgabe setzt du die Bücher-API aus allen Teilen dieses Abschnitts zusammen, noch mit den Daten im Speicher.
Zum Mitnehmen
Router, Prüfung und eine Fehlerform ergeben zusammen eine API, die überall gleich antwortet, und mit curl lässt sie sich ohne eigene Seite prüfen. Die Daten liegen noch im Speicher und sind nach einem Neustart weg.
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.