Übungsaufgaben zu Anforderungen und API-Vertrag: Mitfahrgesuche planen

Kopiere den Text in ein KI-Sprachmodell Deiner Wahl und passe Kompetenzstufe, Anzahl, Bearbeitungszeit und Szenario bei Bedarf an. Wie die Aufgaben aufgebaut sind, beschreibt der Artikel Wie sind die Aufgaben aufgebaut?. Prüfe die Ergebnisse mit dem Lehrartikel: KI-Sprachmodelle machen Fehler.

Erstelle neue Übungsaufgaben zum Thema „Anforderungen und API-Vertrag:
Mitfahrgesuche planen“.

Bauplan: Halte Dich an Aufbau, Kompetenzstufen, Operatoren,
Anforderungsbereiche, Punkte und Zeitschätzung, die im Artikel
https://oer-informatik.de/aufgaben-aufbau beschrieben sind.

Fachliche Grundlage:
- https://oer-informatik.de/spring-boot-anforderungen-api-entwurf
- https://oer-informatik.de/szenario-mitfahrlabor
- https://oer-informatik.de/rest-grundlagen
- https://oer-informatik.de/v-modell
- Stilbeispiel: https://oer-informatik.de/spring-boot-anforderungen-api-entwurf-uebungsaufgaben

Die Aufgaben sollen Inhalte zu diesen Schlagwörtern abdecken:
- OpenAPI
- API-Entwurf
- User Story
- Abnahmekriterien
- V-Modell
- HTTP-Statuscodes
- Zustandsdiagramm
- REST-API

Kompetenzstufe: Kernkompetenz (alternativ: Basiskompetenz, Profilkompetenz, Expertise)
Anzahl: 1 Aufgabe mit Teilaufgaben
Bearbeitungszeit in Minuten ca.: <5 bis 30 min>
Szenario: eines der Szenarien aus dem Bauplan

Vorgehen:
1. Lies zuerst die verlinkten Artikel. Kannst Du keine Webseiten
   abrufen, sag mir das, statt zu raten.
2. Steht bei einer Angabe noch ein Platzhalter in <…>, frag mich
   zuerst danach. Richte Punkte und Zahl der Teilaufgaben nach der
   Bearbeitungszeit (ca. 0,9 min je Punkt).
3. Gib je Aufgabe Titel mit Kompetenzstufe, Ausgangssituation und
   Teilaufgaben mit Operator und Punktzahl aus, dazu die geschätzte
   Bearbeitungszeit.
4. Gib die Beispiellösungen mit Punkteverteilung erst aus, wenn ich
   danach frage.

Je Zeile 2 Punkte (1 Punkt Entwurfsstufe, 1 Punkt Testebene):

Je Zeile 2 Punkte (1 Punkt Methode und Pfad, 1 Punkt Statuscode):

Als Mitfahrende*r ohne Auto möchte ich ein Gesuch mit Haltepunkt, Richtung, Datum und Zeitfenster einstellen, damit Fahrer*innen sehen, dass ich eine Mitfahrgelegenheit brauche. (Rolle, Ziel, Nutzen je 1 Punkt, höchstens 2 Punkte; andere Formulierungen mit allen drei Teilen sind richtig.)

Je Kriterium 2 Punkte (vollständige Form 1 Punkt, überprüfbares Ergebnis 1 Punkt), zum Beispiel:

• AK-G.1: Angenommen, Oksana Melnyk hat für Montag in Richtung „zur Schule“ noch kein offenes Gesuch. Wenn sie für Montag ein Gesuch ab Gütersloh mit dem Zeitfenster 06:45 bis 07:15 Uhr einstellt, dann ist das Gesuch gespeichert und „offen“.

• AK-G.2: Angenommen, eine Mitfahrerin ist am Tag der Fahrt noch nicht 18 und es liegt keine Einwilligung der Eltern vor. Wenn sie ein Gesuch einstellt, dann wird es abgelehnt.

• AK-G.3: Angenommen, Oksana Melnyk hat für Montag in Richtung „zur Schule“ bereits ein offenes Gesuch. Wenn sie ein zweites für denselben Tag und dieselbe Richtung einstellt, dann wird es abgelehnt.

Weitere richtige Fehlerfälle: Zeitfenster mit Ende vor dem Beginn, Datum in der Vergangenheit, unbekannter Haltepunkt.

Je Regel 1 Punkt:

• Datum angegeben: Vertrag (required), denn das sieht man der Anfrage allein an.
• Zeitfenster: Backend. Beide Werte stehen zwar in der Anfrage, aber ein OpenAPI-3.0-Schema kann zwei Felder nicht miteinander vergleichen. (Wer argumentiert, dass dies eine einfache Prüfung im Controller oder in einer eigenen Validierungsannotation ist, liegt ebenfalls richtig, solange klar ist, dass openapi.yaml sie nicht ausdrückt.)
• Einwilligung: Backend, braucht Geburtsdatum und Einwilligung aus den gespeicherten Daten der Person.
• Ein offenes Gesuch: Backend, braucht die schon gespeicherten Gesuche der Person.

Je Funktion 2 Punkte (Methode und Pfad 1 Punkt, Codes 1 Punkt):

Auch 409 statt 422 für ein zweites offenes Gesuch lässt sich begründen, weil es um einen Konflikt mit vorhandenen Daten geht.

Zurückziehen ist ein Zustandswechsel. Das Gesuch soll erhalten bleiben, damit Fahrer*innen, die es gerade ansehen, den Hinweis „zurückgezogen“ statt „nicht gefunden“ erhalten und damit später nachvollziehbar ist, wie viele Gesuche vermittelt wurden. PATCH ändert nur den Status. (Begründung mit Zustandswechsel 1 Punkt, Folge für Nutzende oder Auswertung 1 Punkt)

Das Feld art bekommt einen weiteren erlaubten Wert: enum: [Angebot, Gesuch] (1 Punkt). Für ein Gesuch steht unter zeit der Beginn des Zeitfensters und unter plaetze die Zahl 1, so wie in der View v_monitor des Szenarios; das wird in der Beschreibung des Schemas festgehalten (1 Punkt). Namen und Pseudonyme bleiben weiterhin ausgeschlossen.

components:
  schemas:
    GesuchStatus:
      type: string
      enum: [offen, vermittelt, zurueckgezogen, abgelaufen]

    GesuchNeu:
      type: object
      required: [mitfahrerId, haltepunktId, richtung, datum, zeitVon, zeitBis]
      properties:
        mitfahrerId:
          type: integer
          format: int64
        haltepunktId:
          type: integer
          format: int64
        richtung:
          $ref: '#/components/schemas/Richtung'
        datum:
          type: string
          format: date
        zeitVon:
          type: string
          pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$'
        zeitBis:
          type: string
          pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$'
          description: muss nach zeitVon liegen (prüft das Backend)

    Gesuch:
      allOf:
        - $ref: '#/components/schemas/GesuchNeu'
        - type: object
          required: [id, status]
          properties:
            id:
              type: integer
              format: int64
            status:
              $ref: '#/components/schemas/GesuchStatus'

Bewertung: Pflichtfelder vollständig (2 Punkte), Typen und Formate passend (2 Punkte), Richtung per $ref wiederverwendet (1 Punkt), Uhrzeiten mit Muster (1 Punkt), Gesuch mit id und status (2 Punkte). Gesuch darf auch ohne allOf mit allen Feldern notiert werden.

paths:
  /gesuche:
    post:
      tags: [gesuche]
      operationId: stelleGesuchEin
      summary: ein Mitfahrgesuch einstellen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GesuchNeu'
      responses:
        '201':
          description: Gesuch angelegt
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gesuch'
        '400':
          $ref: '#/components/responses/UngueltigeAnfrage'
        '404':
          $ref: '#/components/responses/NichtGefunden'
        '422':
          $ref: '#/components/responses/FachregelVerletzt'

Bewertung: Pfad, Methode und operationId (1 Punkt), Body mit $ref auf GesuchNeu (1 Punkt), 201 mit Gesuch (1 Punkt), Fehlerantworten (1 Punkt).

Je Fehler 2 Punkte (Fehler mit Begründung 1 Punkt, Korrektur 1 Punkt):

1. Parametername passt nicht zum Platzhalter: Der Pfad enthält {id}, der Parameter heißt gesuchId. OpenAPI verlangt, dass jeder Platzhalter im Pfad einen gleichnamigen Pfadparameter hat. Korrektur: Pfad /gesuche/{gesuchId}.

2. Pfadparameter optional: Pfadparameter müssen required: true haben, denn ohne sie gibt es den Pfad nicht. Korrektur: required: true.

3. Falscher Erfolgscode: GET liest nur und legt nichts an; 201 Created passt nicht. Korrektur: '200'.

4. operationId doppelt: holeGesuch kommt zweimal vor. Die operationId muss in der ganzen Datei eindeutig sein, weil daraus Methodennamen erzeugt werden. Korrektur: für die zweite Operation z. B. zieheGesuchZurueck.

5. Verb im Pfad und ID als Query-Parameter: /gesuche/zurueckziehen benennt eine Aktion statt einer Ressource. Korrektur: PATCH /gesuche/{gesuchId} mit {"status": "zurueckgezogen"}.

6. GET ändert den Zustand: GET muss safe sein, sonst ziehen Crawler, Caches oder ein erneutes Laden der Seite Gesuche zurück. Korrektur: PATCH (siehe 5.)

Ebenfalls richtig erkannt (als Ersatz für einen der sechs, ohne Extrapunkte): Für ein unbekanntes Gesuch fehlt die Antwort 404; nach den Entwurfsregeln der API hat jeder Abruf über eine ID diese Antwort. Korrektur: '404': $ref: '#/components/responses/NichtGefunden'.

Bewertung: Start nach „offen“ (1 Punkt), vier Zustände (2 Punkte), drei Transitionen mit passenden Auslösern (3 Punkte), Ablauf als Zeit- oder Änderungsereignis, z. B. when(datum < heute) (1 Punkt), Endzustände (1 Punkt).

Wenn eine Buchung, die aus einem Gesuch entstanden ist, den Zustand „bestätigt“ erreicht, wechselt das Gesuch nach „vermittelt“ (1 Punkt). Weil dabei zwei Objekte gemeinsam geändert und gespeichert werden, gehört die Regel in den Service, der beide in einer Transaktion ändert (1 Punkt). Wer stattdessen die Domäne nennt und begründet, dass der Service nur aufruft, liegt ebenfalls richtig.