API Reference

StoreStash bietet eine RESTful API unter /api/v1/. Alle Responses sind JSON.

Base URL

http://localhost:3000/api/v1

Authentifizierung

Aktuell (v0.9.x)

Die API ist noch ohne Authentifizierung erreichbar. Ab v0.10.0 wird Auth eingeführt (Sessions, API-Keys, Kiosk-Tokens).

Allgemeine Konventionen

• IDs sind UUIDs (v4)
• Timestamps im ISO 8601 Format
• Fehler als { "detail": "Fehlerbeschreibung" }
• Pagination über page und page_size Query-Parameter
• Content-Type: application/json

HTTP Status Codes

Code	Bedeutung
200	Erfolg
201	Erstellt
204	Gelöscht (kein Body)
400	Ungültige Anfrage (Validierung)
404	Nicht gefunden
422	Unprocessable Entity (Pydantic-Fehler)
429	Rate-Limit überschritten
500	Interner Serverfehler

Rate-Limiting

Nginx limitiert auf 30 Requests/Sekunde pro IP mit Burst von 20.

Endpoints

Resource	Endpoint	Methoden
Products	/products	GET, POST, PATCH, DELETE
Stock	/stock	GET, POST
Categories	/categories	GET, POST, PATCH, DELETE
Locations	/locations	GET, POST, PATCH, DELETE
Barcode	/barcode/{code}	GET

Swagger UI

Im Debug-Modus (DEBUG=true) ist die interaktive Swagger-Dokumentation unter http://localhost:8000/docs verfügbar (direkt am Backend, nicht über Nginx).