54 lines
2.1 KiB
Plaintext
54 lines
2.1 KiB
Plaintext
---
|
|
description: Nie API-Verträge raten — immer Backend-Doku lesen
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Keine angenommenen APIs
|
|
|
|
API-Shapes, Endpoints und Response-Felder **niemals erraten**, **niemals** aus ähnlichen Endpoints ableiten, **niemals** im Chat „vorschlagen“ und dann direkt implementieren.
|
|
|
|
## Quelle der Wahrheit (in dieser Reihenfolge)
|
|
|
|
1. **Laufendes Backend** — `dashback/docs/api/` (Markdown pro Route) und `dashback/docs/api/openapi.json`
|
|
2. **`src/api/index.js`** — nur Spiegel des Backend-Vertrags, keine Erfindung
|
|
3. **Explizite User-Vorgabe** — nur wenn der User den Vertrag wörtlich nennt
|
|
|
|
Fehlt (1): **nicht implementieren**. Stattdessen Doku lesen oder User fragen.
|
|
|
|
## Verboten
|
|
|
|
```js
|
|
// ❌ „PATCH liefert { article }, also sicher auch POST …/image“
|
|
requireObject(res.article, 'article');
|
|
|
|
// ❌ Endpoint oder Feldname erfinden
|
|
return httpMultipart(`/api/article/${sku}/photos`, …);
|
|
|
|
// ❌ Response-Shape aus Konvention ableiten
|
|
onArticleUpdated?.(res.article ?? res.data);
|
|
```
|
|
|
|
```js
|
|
// ✅ Vertrag aus dashback übernommen, in index.js dokumentiert
|
|
// POST /api/article/:sku/image → 201 { image: { picId, sort, full, thumb, hash, thumbHash } }
|
|
requireObject(res.image, 'image');
|
|
```
|
|
|
|
## Pflicht-Workflow bei neuem oder geändertem Endpoint
|
|
|
|
1. Route in `dashback/docs/api` oder `openapi.json` finden und lesen
|
|
2. Method, Path, Request-Body, Status-Codes, Response-JSON exakt notieren
|
|
3. `src/api/index.js` kommentieren und Client-Methode schreiben
|
|
4. Response mit `requireObject` / `requireArray` / `requireDefined` aus `apiShape.js` validieren
|
|
5. Kein Frontend-Code, der Felder nutzt, die nicht im Vertrag stehen (z. B. `photo.url` wenn nur `thumbHash` dokumentiert ist)
|
|
|
|
## Erlaubt
|
|
|
|
- **Backend-Doku aktualisieren**, wenn der User den Vertrag bewusst ändert — danach Frontend anpassen
|
|
- **Blockieren mit Frage**, wenn Vertrag unklar oder widersprüchlich ist
|
|
|
|
## Zusammenspiel mit `no-silent-fallbacks`
|
|
|
|
- Keine Fallbacks auf alternative Feldnamen oder Endpoints
|
|
- Kein „vielleicht heißt es `article` oder `image`“ — der Vertrag legt es fest
|