Aufgabe 15 - Die eigene API

Aufgabe 15 - Die eigene API

Worum geht es?

Der Papier-Entwurf aus Aufgabe 10 wird Wirklichkeit: Sie implementieren die Buffet-API als Next.js-Route-Handler, exakt nach Ihrer eigenen Dokumentation, und nehmen sie ohne Frontend ab (siehe Kapitel Next.js II). Die Doku ist dabei bindend: Wo die Implementierung abweichen muss, wird zuerst die Doku geändert, mit Changelog-Zeile.

Was Sie dafür brauchen

• Kapitel Next.js II; Ihr API-Dokument aus Aufgabe 10 (Version 2).
• Ein Next.js-Projekt; die Daten leben vorerst in einer In-Memory-Struktur (Persistenz folgt in Aufgabe 19).

Welche Kompetenzen Sie erwerben und zeigen

• Sie implementieren REST-Endpunkte als Route Handlers mit korrekten Statuscodes.
• Sie halten einen dokumentierten Vertrag verbindlich ein.
• Sie nehmen eine API systematisch von außen ab, inklusive aller Fehlerfälle.

Pädagogische Einordnung

• Reproduktion: die Handler-Muster des Kapitels auf die ersten Endpunkte anwenden (Teil A).
• Reorganisation und Transfer: Zustandsübergänge und Regeln des eigenen Entwurfs implementieren (Teile B und C).
• Reflexion, Problemlösung und Urteilsbildung: eine fremde API nur anhand ihrer Doku abnehmen und Vertragslücken aufdecken (Teil D).

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt. Teil D ist der Expertenteil.

Teil A - Lesen und Anlegen

1. GET /api/items: das Tagesangebot; POST /api/items: neuen Artikel anlegen. Die Buffet-Rolle wird vorerst über einen HTTP Header x-role: buffet simuliert (der saubere Ersatz kommt in Aufgabe 20).
2. POST /api/orders: Bestellung anlegen. Validiert werden die Regeln Ihrer Doku (1 bis 5 Positionen, Artikel existiert, Menge verfügbar, Bestellschluss); bei Erfolg werden Mengen abgebucht, Abholnummer vergeben und mit 201 samt Bestellobjekt geantwortet.
3. Jede Antwort, auch jede Fehlerantwort, entspricht exakt dem Format Ihrer Doku (Statuscode und Fehler-JSON).

Teil B - Zustandsübergänge

1. GET /api/orders: Buffet-Rolle sieht alle, Schüler nur die eigenen (über den Header simuliert).
2. PATCH /api/orders/[id]: Statuswechsel open zu ready zu pickedUp; ungültige Sprünge antworten mit 409 im Fehlerformat.
3. DELETE /api/orders/[id]: Storno nur im Status open, sonst 409; unbekannte ID 404.

Teil C - Abnahme von außen

1. Schreiben Sie ein Abnahmeskript: eine Shell-Datei (.sh), die Ihre API der Reihe nach mit curl-Befehlen aufruft. Über jeden Befehl schreiben Sie als Kommentar den erwarteten Statuscode. Das Skript spielt einen kompletten Lebenszyklus durch: Artikel anlegen, bestellen, fertig melden, abholen, Storno-Versuch (muss mit 409 scheitern).
2. Ergänzen Sie die Negativ-Abnahme: kaputtes JSON, leere Positionsliste, sechs Positionen, unbekannter Artikel, doppelter Statuswechsel. Jede dokumentierte Fehlerantwort wird einmal real beobachtet.
3. Gleichen Sie am Ende Doku und Wirklichkeit ab: Jede Abweichung, die die Abnahme fand, wird behoben oder als Doku-Änderung mit Changelog-Zeile nachgezogen.

Teil D - Expertenteil: Die Fremd-Abnahme

1. Tauschen Sie mit dem Team, dessen Entwurf Sie in Aufgabe 10 reviewt haben: Sie testen deren laufende API, ausschließlich mit deren Dokument in der Hand; kein Blick in den Code, keine Rückfragen.
2. Führen Sie ein Abnahmeprotokoll: geprüfter Fall, erwartetes Verhalten laut Doku, beobachtetes Verhalten, Befund. Jede Überraschung ist per Definition ein Doku- oder Implementierungsfehler des anderen Teams; formulieren Sie die Befunde wie Review-Anmerkungen (Fundstelle, Kriterium, Vorschlag).
3. Nehmen Sie die Befunde am eigenen Projekt entgegen und beheben Sie mindestens zwei.
4. Beurteilen Sie in drei Sätzen: Was hat die Fremd-Abnahme gefunden, was die eigene Abnahme aus Teil C nicht fand, und warum ist der fremde Blick hier strukturell überlegen?

Wissenscheck

1. Wie kommen die HTTP-Methoden eines Endpunkts in Next.js zustande?
2. Warum antwortet ein kaputter Request-Body mit 400 und nicht mit 500?
3. Welche Statuscodes gehören zu: erfolgreich angelegt, erfolgreich gelöscht, unbekannte ID, ungültiger Statuswechsel?
4. Was bedeutet “die Doku ist bindend” praktisch, wenn die Implementierung abweichen muss?
5. Warum ist der In-Memory-Speicher nach einem Neustart leer, und in welchem Modul-Kontext lebt er?

Abgabe

Git-Repository, Abnahmeskript samt Negativ-Abnahme, das Fremd-Abnahmeprotokoll und die aktualisierte API-Doku mit Changelog.