Aufgabe 14 - Reifegrad-Analyse einer fremden API

Aufgabe 14 - Reifegrad-Analyse einer fremden API

Worum geht es?

Sie nehmen eine öffentlich zugängliche Schnittstelle auseinander und ordnen sie in die Richardson-Reifegrade ein (siehe Kapitel Schnittstellen im Vergleich). Fremde APIs zu lesen ist die Tätigkeit, die Sie im Berufsleben häufiger ausüben werden als APIs zu bauen, und sie schärft den Blick für den eigenen Entwurf im nächsten Kapitelabschnitt.

Was Sie dafür brauchen

• Kapitel Schnittstellen im Vergleich, Abschnitte REST in der Tiefe und Statuscodes sind Teil des Vertrags.
• curl oder ein Werkzeug wie Bruno, Insomnia oder Postman.
• Eine öffentliche API ohne Anmeldung. Geeignet sind etwa die Schnittstellen von Wikipedia, der Open-Meteo-Wetterdienst, das offene Datenportal des Bundes oder eine API aus dem Katalog Ihrer Lehrkraft.

Welche Kompetenzen Sie erwerben und zeigen

• Sie ordnen eine fremde Schnittstelle in die Richardson-Reifegrade ein und begründen die Einordnung.
• Sie prüfen, ob Methoden sicher und idempotent verwendet werden und ob Statuscodes sachgerecht gewählt sind.
• Sie erkennen Schwächen in einem fremden Entwurf und schlagen konkrete Verbesserungen vor.

Pädagogische Einordnung

• Reproduktion: die vier Reifegrade benennen und einfache Anfragen absetzen (Teil A).
• Reorganisation und Transfer: eine fremde API systematisch untersuchen und einordnen (Teil B).
• Reflexion, Problemlösung und Urteilsbildung: Schwächen aufzeigen und einen besseren Entwurf vorschlagen (Teil C).

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt.

Teil A - Aufwärmen an bekannten Beispielen

1. Schreiben Sie die vier Richardson-Reifegrade untereinander und ergänzen Sie zu jedem in einem Satz das Merkmal, an dem man ihn erkennt.

2. Ordnen Sie die folgenden sechs Aufrufe einem Reifegrad zu und begründen Sie jede Zuordnung in einem halben Satz:

   • POST /api mit {"action": "getUser", "id": 7}
   • GET /users/7
   • POST /users/7/delete
   • DELETE /users/7
   • GET /users/7 mit einer Antwort, die Links auf /users/7/orders enthält
   • POST /createUser

3. Setzen Sie drei einfache GET-Anfragen an Ihre gewählte API ab und speichern Sie die Antworten. Notieren Sie zu jeder den Statuscode und die ersten Zeilen des Rumpfes.

4. Rufen Sie eine Adresse ab, die es sicher nicht gibt, etwa mit einer erfundenen ID. Notieren Sie den Statuscode. Prüfen Sie, ob er zum Fall passt, und schreiben Sie in einem Satz, welcher Code richtig wäre.

Teil B - Die Untersuchung

1. Legen Sie eine Tabelle Ihrer untersuchten API an mit den Spalten Methode und Pfad, Zweck, Statuscode bei Erfolg, Statuscode bei Fehler. Tragen Sie mindestens fünf Endpunkte ein.

2. Prüfen Sie die Pfade auf Verben. Notieren Sie jeden Pfad, in dem ein Verb steckt, und schreiben Sie daneben, wie er ressourcenorientiert aussehen würde.

3. Prüfen Sie mit curl -i, welche Kopfzeilen zurückkommen. Suchen Sie nach Cache-Control, ETag und Location und notieren Sie, welche davon vorhanden sind.

4. Setzen Sie dieselbe GET-Anfrage zweimal ab und vergleichen Sie die Antworten. Beantworten Sie in zwei Sätzen, ob sich der Aufruf sicher verhält, also ob er etwas verändert.

5. Ordnen Sie die API einem Reifegrad zu. Schreiben Sie eine Begründung von vier bis fünf Sätzen, in der Sie mindestens drei Beobachtungen aus den Punkten 1 bis 4 als Belege verwenden.

6. Suchen Sie die Dokumentation der API. Notieren Sie, ob es eine OpenAPI-Beschreibung gibt, und beantworten Sie in zwei Sätzen, was Sie ohne Dokumentation nicht herausfinden konnten.

Teil C - Befund und Gegenentwurf

1. Schreiben Sie einen Befundbericht von etwa 15 Zeilen. Er nennt drei Stärken und drei Schwächen der untersuchten API, jede mit einem konkreten Beleg aus Ihrer Tabelle.

2. Nehmen Sie die schwächste Stelle und entwerfen Sie sie neu. Legen Sie eine Gegenüberstellung an: links der bestehende Aufruf mit Methode, Pfad und Statuscodes, rechts Ihr Vorschlag. Begründen Sie in drei bis vier Sätzen, was Ihr Entwurf besser macht.

3. Untersuchen Sie das Fehlerverhalten genauer. Provozieren Sie drei verschiedene Fehler, etwa eine unbekannte ID, einen fehlenden Pflichtparameter und einen ungültigen Wert. Notieren Sie zu jedem den Statuscode und den Rumpf.

4. Beurteilen Sie das Fehlermodell in drei bis vier Sätzen: Kann ein Aufrufer allein am Statuscode entscheiden, was zu tun ist? Falls nicht, beschreiben Sie, was dafür fehlt.

5. Prüfen Sie, ob die API die Verwechslung von 401 und 403 begeht oder Fehler als 200 mit einem error-Feld ausliefert. Falls ja, beschreiben Sie in drei Sätzen, welches Problem das einem Aufrufer bereitet.

6. Ziehen Sie zwei Lehren für Ihr eigenes Projekt. Schreiben Sie jede als Regel in einem Satz auf und legen Sie beide in docs/architektur.md ab. Sie werden in Aufgabe 15 dagegen entwerfen.

Wissenscheck

1. Was kennzeichnet die Reifegrade 0 bis 3, und wo liegt praktisch das meiste, was sich REST-API nennt?
2. Warum ist Grad 3 selten, und in welchen Systemen zahlt er sich aus?
3. Was bedeutet „sicher”, was bedeutet „idempotent”, und welche Methoden sind was?
4. Warum darf ein GET niemals etwas verändern? Nennen Sie zwei Beteiligte, die sich darauf verlassen.
5. Wann antwortet ein Server mit 401, wann mit 403, und was macht ein Client bei einer Verwechslung falsch?
6. Wann ist 409 richtig, wann 422?
7. Warum ist eine Fehlermeldung mit Statuscode 200 für jede Zwischenstation ein Problem?

Abgabe

Eine Datei protokoll.md mit den Zuordnungen aus Teil A, der Endpunkttabelle, den Kopfzeilenbefunden und der begründeten Reifegrad-Einordnung aus Teil B sowie dem Befundbericht, der Gegenüberstellung und den drei provozierten Fehlern aus Teil C. Die beiden Regeln für das eigene Projekt stehen in docs/architektur.md.