Aufgabe 10 - API auf Papier

Aufgabe 10 - API auf Papier

Worum geht es?

Bevor Sie eine Schnittstelle bauen, entwerfen Sie sie: eine vollständige REST-API als Dokument, das ein anderes Team umsetzen könnte, dazu ein gegenseitiges Review (siehe Kapitel Schnittstellen entwerfen). Der Entwurf ist verbindlich: Genau dieses Dokument wird in Aufgabe 15 implementiert; jede Lücke von heute ist ein Bug von übermorgen.

Was Sie dafür brauchen

• Kapitel Schnittstellen entwerfen vollständig; Kapitel HTTP und Schnittstellen.
• Ein Markdown-Dokument, Zweierteams.

Welche Kompetenzen Sie erwerben und zeigen

• Sie legen Ressourcen, Endpunkte, Methoden und Statuscodes nach REST-Konventionen fest.
• Sie definieren JSON-Verträge mit verbindlichen Beispielen und einem konsistenten Fehlerformat.
• Sie reviewen fremde Entwürfe systematisch und arbeiten Reviews professionell ein.

Pädagogische Einordnung

• Reproduktion: die REST-Konventionen auf ein gegebenes Szenario anwenden (Teil A).
• Reorganisation und Transfer: Formate und Fehlerfälle vollständig dokumentieren (Teil B).
• Reflexion, Problemlösung und Urteilsbildung: fremde Entwürfe prüfen, Kritik begründen und den eigenen Entwurf verteidigen oder korrigieren (Teile C und D).

Szenario: Schulbuffet-Vorbestellung

Schülerinnen und Schüler sehen das Tagesangebot des “Safi”-Buffets, bestellen bis 11:00 Uhr vor und holen mit einer Abholnummer ab. Das Safi-Team pflegt das Angebot (Artikel mit Name, Preis, verfügbarer Menge) und arbeitet die Bestellliste ab (offen, fertig, abgeholt). Eine Bestellung enthält 1 bis 5 Positionen; stornieren geht nur, solange sie offen ist.

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt. Ressourcen- und Feldnamen im Entwurf sind englisch (/api/items, /api/orders), die Dokumentationstexte deutsch. Teil D ist der Expertenteil.

Teil A - Ressourcen und Endpunkte

1. Bestimmen Sie die Ressourcen des Szenarios (Substantive!) mit je einem Satz Begründung. Kandidaten: items, orders; prüfen Sie, ob die Abholnummer eine eigene Ressource ist oder ein Feld.
2. Erstellen Sie die Endpunkt-Tabelle: Methode, Pfad, Zweck, wer darf das (Schüler oder Buffet-Team). Jede Aktion steckt in der Methode, keine Verben in Pfaden.
3. Legen Sie Query-Parameter fest, wo Filtern nötig ist (etwa GET /api/orders?state=open).

Teil B - Der Datenvertrag

1. Definieren Sie für jeden Endpunkt Request- und Response-Body als konkretes JSON-Beispiel (nicht abstrakt); Eingabeformat und Ausgabeformat getrennt, wo sie sich unterscheiden (der Server vergibt id, pickupNumber, state, createdAt).
2. Legen Sie die Statuscodes fest: wann 200/201/204/400/403/404/409. Entscheiden und begründen Sie insbesondere: Welcher Code, wenn die Menge nicht reicht? Welcher, wenn nach 9:00 Uhr bestellt wird?
3. Definieren Sie das einheitliche Fehlerformat (error mit code, message, optional details) und je ein Beispiel für einen Validierungs- und einen Konfliktfehler.

Teil C - Das Review

Tauschen Sie Entwürfe mit einem anderen Team und prüfen Sie systematisch:

1. Lässt sich jede Anforderung des Szenarios mit den Endpunkten abbilden? Spielen Sie die Abläufe durch (bestellen, abholen, stornieren, Angebot pflegen).
2. Sind die Beispiele in sich widerspruchsfrei (Feldnamen, Typen, Formate konsistent)?
3. Gibt es Konventionsverstöße (Verben in Pfaden, falsche Codes, fehlende Fehlerfälle)?
4. Was passiert bei gleichzeitiger Bestellung des letzten Artikels? Ist der Fall dokumentiert?

Schreiben Sie mindestens vier konkrete Anmerkungen; jede nennt Fundstelle, verletztes Kriterium und einen Vorschlag.

Teil D - Expertenteil: Einarbeiten und Härtetest

1. Arbeiten Sie das erhaltene Review ein und dokumentieren Sie je Anmerkung: übernommen (wie?) oder begründet abgelehnt. Das Ergebnis ist Version 2 des Dokuments; Version 1 bleibt als Anhang erhalten.
2. Härtetest des eigenen Entwurfs: Schreiben Sie, nur auf Basis des fremden Dokuments (nicht Ihres eigenen), die TypeScript-Interfaces und zwei beispielhafte fetch-Aufrufe gegen die fremde API. Jede Stelle, an der Sie raten mussten, geht als Nachtrag ans andere Team.
3. Ergänzen Sie in Version 2 einen Abschnitt “Änderungsregeln”: Welche Änderungen an dieser API wären additiv, welche brechend? Je zwei Beispiele.
4. Beurteilen Sie in drei Sätzen: Welche Review-Anmerkung hätte, unentdeckt, den teuersten Implementierungsfehler verursacht, und warum?

Wissenscheck

1. Warum stehen in REST-Pfaden Substantive und keine Verben?
2. Mit welchem Statuscode und welchem Body antwortet ein gelungenes POST /api/orders?
3. Wofür steht 409, und welcher Fall des Szenarios braucht ihn?
4. Warum sind konkrete Beispiel-JSONs Pflicht und abstrakte Feldlisten nicht genug?
5. Woran erkennt man eine brechende API-Änderung?

Abgabe

API-Dokument in Version 2 (mit Version 1 als Anhang), das erhaltene und das geschriebene Review samt Einarbeitungsprotokoll, die Interfaces aus dem Härtetest. Dieses Dokument wird in Aufgabe 15 implementiert.