Aufgabe 06-1a - API auf Papier

Lernziele

Du legst Ressourcen, Endpunkte, Methoden und Statuscodes nach REST-Konventionen fest.
Du definierst JSON-Verträge mit verbindlichen Beispielen und einem einheitlichen Fehlerformat.
Du reviewst fremde Entwürfe systematisch und arbeitest ein erhaltenes Review nachvollziehbar ein.

Ausgangslage

Bevor ihr eine Schnittstelle baut, entwerft ihr sie: eine vollständige REST-API als Dokument, das ein anderes Team umsetzen könnte (siehe Kapitel Schnittstellen entwerfen, Einheit 6.1 für die Stufe Wesentlich_überwiegend, Einheit 6.2 ab Wesentlich_vollständig). Der Entwurf ist verbindlich: Genau dieses Dokument wird in Aufgabe 09-1a implementiert; jede Lücke von heute ist ein Bug von übermorgen.

Szenario: Schulbuffet-Vorbestellung. Schülerinnen und Schüler sehen das Tagesangebot des “Safi”-Buffets, bestellen bis 9: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.

Ressourcen- und Feldnamen im Entwurf sind englisch (/api/items, /api/orders), die Dokumentationstexte deutsch.

Allgemein

Projektordner anlegen siehe https://qiz.at/projektordner

Lies vorher kurz https://qiz.at/assignmentsabgabe durch.
Nur vollständige Abgaben (siehe https://qiz.at/rules) können positiv bewertet werden.
Abgabe- und Testdetails siehe https://qiz.at/assignmentsabgabe
Die Übung liegt als Unterordner uebung-06-1a in deinem Jahres-Repository SJ26_27_4AHITM_SEW_<Benutzername>_exercises. Ihr arbeitet zu zweit an einem Dokument api.md; beide legen es in ihrem eigenen Repository ab und nennen im README.md die Teampartnerin oder den Teampartner.

Wesentlich_überwiegend

Aufgabe

Bestimmt die Ressourcen des Szenarios mit je einem Satz Begründung. Kandidaten: items, orders; prüft, ob die Abholnummer eine eigene Ressource ist oder ein Feld.
Erstellt die Endpunkt-Tabelle: Methode, Pfad, Zweck, wer das darf (Schüler:in oder Buffet-Team). Jede Aktion steckt in der Methode, keine Verben in Pfaden.
Legt Query-Parameter fest, wo gefiltert werden muss, etwa GET /api/orders?state=open.
Definiert für jeden Endpunkt Request- und Response-Body als konkretes JSON-Beispiel; Eingabe- und Ausgabeformat getrennt, wo sie sich unterscheiden (der Server vergibt id, pickupNumber, state, createdAt).

Tipp: Geht die Abläufe des Szenarios einmal laut durch: Angebot ansehen, bestellen, abholen, stornieren, Angebot pflegen. Jeder Ablauf braucht mindestens einen Endpunkt. Preise als ganze Zahl in Cent, Zeitstempel im ISO-8601-Format (Einheit 6.1).

Bewertungskriterien

Vollständig, wenn:

die Ressourcen begründet sind und die Abholnummer richtig eingeordnet ist.
die Endpunkt-Tabelle alle Abläufe des Szenarios abdeckt, ohne Verben in Pfaden, mit Rollen.
jedes Beispiel-JSON zu den Feldnamen passt und Eingabe- und Ausgabeformat getrennt sind.

Abgabe

Wie unter Allgemein.

Wesentlich_vollständig

Für alle, die in der Einheit mit den Schritten oben fertig sind bzw. optional (= freiwillig), wenn du in der Einheit nicht fertig wirst.

Aufgabe

Erweitere (siehe Erweitern in https://qiz.at/rules) den vollständigen Teil der vorherigen Stufe dieser Datei (ändere oder lösche nur, was für diese Aufgabe unbedingt notwendig ist):

Legt die Statuscodes fest: wann 200, 201, 204, 400, 403, 404, 409. Entscheidet und begründet insbesondere: Welcher Code, wenn die Menge nicht reicht? Welcher, wenn nach 9:00 Uhr bestellt wird?
Definiert das einheitliche Fehlerformat (error mit code, message, optional details) und gebt je ein Beispiel für einen Validierungs- und einen Konfliktfehler.
Bringt das Dokument in die Form aus Einheit 6.2: pro Endpunkt Zweck, Request-Body, alle Antworten mit Status und Beispiel.

Tipp: Unterscheidet “die Anfrage ist falsch” (400) von “die Anfrage ist in Ordnung, passt aber nicht zum aktuellen Zustand” (409). Kein Endpunkt bekommt ein eigenes Fehlerformat.

Bewertungskriterien

Vollständig, wenn:

jeder Statuscode einem Fall zugeordnet ist und die Entscheidungen zu Menge und Bestellschluss begründet sind.
das Fehlerformat für alle Fehler gilt und beide Beispiele es einhalten.
jeder Endpunkt Zweck, Body und alle Antworten mit Beispiel dokumentiert.

Abgabe

Wie unter Allgemein.

PlusPlus Aufgabe

Für alle, die in der Einheit mit den Schritten oben fertig sind bzw. optional (= freiwillig), wenn du in der Einheit nicht fertig wirst.

Aufgabe

Erweitere (siehe Erweitern in https://qiz.at/rules) den vollständigen Teil der vorherigen Stufe dieser Datei (ändere oder lösche nur, was für diese Aufgabe unbedingt notwendig ist):

Tauscht Entwürfe mit einem anderen Team und prüft systematisch:

Lässt sich jede Anforderung des Szenarios mit den Endpunkten abbilden? Spielt die Abläufe durch.
Sind die Beispiele in sich widerspruchsfrei (Feldnamen, Typen, Formate)?
Gibt es Verstöße gegen die Konventionen (Verben in Pfaden, falsche Codes, fehlende Fehlerfälle)?
Was passiert, wenn zwei Personen gleichzeitig den letzten Artikel bestellen? Ist der Fall dokumentiert?

Schreibt mindestens vier Befunde in review.md; jeder nennt Fundstelle, verletztes Kriterium und einen Vorschlag.

Tipp: Die fünf Prüffragen aus Einheit 6.2 sind eure Checkliste. Die stärkste Frage ist die letzte: Könntet ihr allein aus dem Dokument einen Client schreiben?

Bewertungskriterien

Vollständig, wenn:

mindestens vier Befunde vorliegen, jeder mit Fundstelle, Kriterium und Vorschlag.
die Abläufe des Szenarios nachweislich durchgespielt wurden.
der Gleichzeitigkeitsfall geprüft ist.

Abgabe

Wie unter Allgemein.

MandalorianPlus Aufgabe

Für alle, die in der Einheit mit den Schritten oben fertig sind bzw. optional (= freiwillig), wenn du in der Einheit nicht fertig wirst.

Aufgabe

Erweitere (siehe Erweitern in https://qiz.at/rules) den vollständigen Teil der vorherigen Stufe dieser Datei (ändere oder lösche nur, was für diese Aufgabe unbedingt notwendig ist):

Arbeitet das erhaltene Review ein und dokumentiert je Befund: übernommen (wie?) oder begründet abgelehnt. Das Ergebnis ist Version 2 des Dokuments; Version 1 bleibt als api-v1.md erhalten.
Härtetest: Schreibt nur auf Basis des fremden Dokuments die TypeScript-Interfaces und zwei beispielhafte fetch-Aufrufe gegen die fremde API in hardening.ts. Jede Stelle, an der ihr raten musstet, geht als Nachtrag ans andere Team.
Ergänzt in Version 2 einen Abschnitt “Änderungsregeln”: Welche Änderungen an dieser API wären additiv, welche brechend? Je zwei Beispiele.
Beurteilt in drei Sätzen: Welcher Befund hätte unentdeckt den teuersten Fehler bei der Implementierung verursacht, und warum?

Tipp: hardening.ts muss nur kompilieren, nicht laufen; die fremde API gibt es noch nicht. Typische Rate-Stellen: Ist die Abholnummer ein String oder eine Zahl? In welcher Zeitzone steht createdAt?

Bewertungskriterien

Vollständig, wenn:

jeder Befund mit “übernommen” oder begründet “abgelehnt” protokolliert ist und Version 1 erhalten bleibt.
hardening.ts kompiliert und die Rate-Stellen als Nachtrag dokumentiert sind.
die Änderungsregeln je zwei richtige Beispiele enthalten und die Beurteilung begründet ist.

Abgabe

Wie unter Allgemein.

Wissenscheck

Warum stehen in REST-Pfaden Substantive und keine Verben?
Mit welchem Statuscode und welchem Body antwortet ein gelungenes POST /api/orders?
Wofür steht 409, und welche Fälle des Szenarios brauchen ihn?
Warum sind konkrete Beispiel-JSONs Pflicht und abstrakte Feldlisten nicht genug?
Woran erkennt man eine brechende API-Änderung?

Zeit dafür

Durchschnittlich bis Wesentlich_vollständig: ca. 100 min

Änderungen

Datum	Änderung
08.10.2026	Ausgangslage: Bestellschluss einheitlich 9:00 Uhr (das Szenario nannte vorher 11:00 Uhr, die Aufgabe zum Statuscode 9:00 Uhr).

Autoren

Oliver Maurhart (MAO)
Michael Gabriel (GAM)

Lizenz

CC-BY-SA

Regeln

https://qiz.at/rules