Beispielarbeiten · Software & Web-Apps

API-Design-Review: Schnittstellenbeschreibung geprüft und überarbeitet

Eine Demo-Beschreibung im OpenAPI-Format mit typischen Mängeln: Verben im Pfad, Listen ohne Seitenaufteilung, fehlende Fehlerantworten, keine Anmeldung, tote Verweise. Der Prüfer findet sie, die überarbeitete Beschreibung besteht.

Musterarbeit (Demo), kein Kundenauftrag. Gebaut als Probeaufgabe mit erfundenen Beispieldaten; die Prüfzahlen unten stammen aus dem automatischen Prüflauf und sind nicht geschönt.

Was gebaut wurde

Pfade nennen Dinge, Listen haben Seitenaufteilung, POST antwortet mit Angelegt
Jede Operation mit operationId und Fehlerantworten, gemeinsames Fehlerformat
Anmeldung und Version im Pfad, alle Verweise lösen sich auf
Betrieb erfunden

api-vorher.json herunterladen api-nachher.json herunterladen

Wie geprüft wurde

Automatischer Prüflauf vom 29.10.2026, aus dem Protokoll (Testdaten erfunden, Zahlen gemessen):

Demo-Schnittstelle: Vorher-Beschreibung 11 Befunde in 10 Arten, Nachher 0
schlechte Gegenprobe 7 Befunde
8 Pruefungen

Alle Prüffälle (8 von 8 grün)

✓ findet die eingebauten fehlerarten
✓ nachher ohne befund
✓ gegenprobe schlechte api faellt durch
✓ gegenprobe leeres dokument faellt durch
✓ nachher ist gueltiges json mit aufloesbaren verweisen
✓ keine ki floskeln
✓ kein versprechen
✓ demo gekennzeichnet

Grenzen

Was diese Probe nicht abdeckt, steht hier, damit niemand mehr erwartet:

Geprueft wird die Beschreibung, nicht der laufende Dienst
Vertragstests gegen den echten Dienst nur mit Zugang und Absprache
Fachliche Felder und Versionierungsstrategie klaert der Kunde mit

Der Bericht

# API-Design-Review - Demo-Betrieb Kornblume (erfunden)

Musterarbeit von GL Tools, kein Kundenauftrag. Gegenstand ist ein Demo-Projekt des erfundenen Betriebs Kornblume, selbst geschrieben, ohne echte Schluessel oder Kundendaten.

## Befunde der Vorher-Beschreibung (11)

- kein gemeinsames fehlerformat
- keine anmeldung
- keine fehlerantworten:GET /getBestellungen
- keine fehlerantworten:POST /getBestellungen
- keine operation id:POST /getBestellungen
- keine version im pfad
- liste ohne seitenaufteilung:GET /getBestellungen
- post ohne 201:POST /getBestellungen
- toter verweis:#/components/responses/Fehlt
- uneinheitliche feldnamen:Bestellung
- verb im pfad:/getBestellungen

## Befunde der Nachher-Beschreibung: 0

## Regeln, nach denen geprueft wurde

Pfade nennen Dinge, keine Verben. Listen haben Seitenaufteilung. Jede Operation hat eine operationId und mindestens eine Fehlerantwort. POST antwortet mit 201. Alle Verweise loesen sich auf. Feldnamen haben einen Stil. Die Version steht im Pfad. Alle Fehler teilen ein Format.

## Was dieses Review nicht kann

Es liest die Beschreibung, nicht den laufenden Dienst. Ob der Server sich an die Beschreibung haelt, zeigen Vertragstests gegen den echten Dienst; die Fachlichkeit (welche Felder ein Kunde braucht) klaert sich im Gespraech.

So etwas für deinen Betrieb?

Beschreib kurz, was du brauchst. Du bekommst einen Festpreis, bevor ich anfange; ohne dein Ja passiert nichts.

Zur Werkstatt