mitmario.dev

Was ist eine API?

Node.js Sandbox 3 Min Lesezeit 3 BeispieleLektion 1 von 8

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

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.

Fünf Tätigkeiten gegen zwei Pfade
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.

Beziehungen und zwei Ausnahmen
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, kostenlos

Zu 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.