API updadte

2025-11-09 11:27:21 +01:00
parent 77206224a2
commit 4953d192c0
8 changed files with 2343 additions and 784 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,185 @@
+# API-Dokumentation
+
+[← Zurück zur Hauptseite](../README.md)
+
+## Übersicht
+
+Die Immorechner-API ist eine vollständige REST-API basierend auf API Platform 4.2 mit OpenAPI/Swagger-Dokumentation.
+
+**Basis-URL:** `http://localhost:8080/api`
+
+**Formate:**
+- `application/ld+json` (Standard, JSON-LD mit Hydra)
+- `application/json` (Einfaches JSON)
+
+## Interaktive Dokumentation
+
+**Swagger UI:** http://localhost:8080/api/docs.html
+
+Hier können Sie alle Endpunkte direkt im Browser testen.
+
+## Authentifizierung
+
+### API-Key (für API-Zugriff)
+
+Fügen Sie den API-Key im Header hinzu:
+
+```bash
+curl -H "X-API-KEY: ihr-api-key-hier" http://localhost:8080/api/immobilies
+```
+
+### API-Key erhalten
+
+```bash
+# User erstellen
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Max Mustermann",
+    "email": "max@example.com",
+    "role": "user"
+  }'
+
+# Response enthält apiKey
+{
+  "apiKey": "a1b2c3d4e5f6...",  # Diesen Key verwenden
+  ...
+}
+```
+
+## Endpunkte
+
+### Bundesländer (Öffentlich)
+
+| Methode | Endpoint | Beschreibung | Auth |
+|---------|----------|--------------|------|
+| GET | `/api/bundeslands` | Alle Bundesländer | Nein |
+| GET | `/api/bundeslands/{id}` | Einzelnes Bundesland | Nein |
+| POST | `/api/bundeslands` | Neues Bundesland erstellen | ADMIN/TECHNICAL |
+| PUT | `/api/bundeslands/{id}` | Bundesland aktualisieren | ADMIN/TECHNICAL |
+| DELETE | `/api/bundeslands/{id}` | Bundesland löschen | ADMIN/TECHNICAL |
+
+**Beispiel:**
+```bash
+curl http://localhost:8080/api/bundeslands
+```
+
+### Heizungstypen (Öffentlich)
+
+| Methode | Endpoint | Beschreibung | Auth |
+|---------|----------|--------------|------|
+| GET | `/api/heizungstyps` | Alle Heizungstypen | Nein |
+| GET | `/api/heizungstyps/{id}` | Einzelner Heizungstyp | Nein |
+| POST | `/api/heizungstyps` | Neuen Typ erstellen | ADMIN/TECHNICAL |
+| PUT | `/api/heizungstyps/{id}` | Typ aktualisieren | ADMIN/TECHNICAL |
+| DELETE | `/api/heizungstyps/{id}` | Typ löschen | ADMIN/TECHNICAL |
+
+### Immobilien (Geschützt)
+
+| Methode | Endpoint | Beschreibung | Auth |
+|---------|----------|--------------|------|
+| GET | `/api/immobilies` | Eigene Immobilien | API-Key |
+| GET | `/api/immobilies/{id}` | Einzelne Immobilie | API-Key |
+| POST | `/api/immobilies` | Neue Immobilie | API-Key |
+| PATCH | `/api/immobilies/{id}` | Immobilie aktualisieren | API-Key |
+| DELETE | `/api/immobilies/{id}` | Immobilie löschen | API-Key |
+
+**Beispiel - Immobilie erstellen:**
+```bash
+curl -X POST http://localhost:8080/api/immobilies \
+  -H "Content-Type: application/json" \
+  -H "X-API-KEY: your-api-key" \
+  -d '{
+    "verwalter": "/api/users/1",
+    "adresse": "Hauptstraße 123, 12345 Musterstadt",
+    "wohnflaeche": 85,
+    "nutzflaeche": 15,
+    "zimmer": 3,
+    "typ": "wohnung",
+    "kaufpreis": 300000,
+    "bundesland": "/api/bundeslands/1",
+    "heizungstyp": "/api/heizungstyps/1"
+  }'
+```
+
+### User (Geschützt)
+
+| Methode | Endpoint | Beschreibung | Auth |
+|---------|----------|--------------|------|
+| GET | `/api/users` | Alle User | API-Key |
+| GET | `/api/users/{id}` | Einzelner User | API-Key |
+| POST | `/api/users` | Neuen User erstellen | Nein* |
+| PUT | `/api/users/{id}` | User aktualisieren | API-Key |
+| DELETE | `/api/users/{id}` | User löschen | API-Key |
+
+*POST ohne Auth zum Registrieren neuer User
+
+## Rollen & Berechtigungen
+
+| Rolle | Rechte |
+|-------|--------|
+| `user` | Eigene Immobilien verwalten |
+| `admin` | Alle Ressourcen, alle Immobilien |
+| `technical` | Bundesländer & Heizungstypen verwalten |
+| `moderator` | Erweiterte Rechte |
+
+## Enums
+
+### ImmobilienTyp
+- `wohnung` - Wohnung
+- `haus` - Haus
+- `grundstueck` - Grundstück
+- `gewerbe` - Gewerbe
+- `buero` - Büro
+
+### UserRole
+- `user` - Benutzer
+- `admin` - Administrator
+- `moderator` - Moderator
+- `technical` - Technischer User
+
+## Pagination
+
+Alle Collection-Endpunkte unterstützen Pagination:
+
+```bash
+# Erste Seite (Standard: 30 Items)
+curl http://localhost:8080/api/immobilies
+
+# Zweite Seite
+curl http://localhost:8080/api/immobilies?page=2
+
+# Custom Page Size
+curl "http://localhost:8080/api/immobilies?itemsPerPage=10"
+```
+
+## Filter
+
+```bash
+# Nach Typ filtern
+curl "http://localhost:8080/api/immobilies?typ=wohnung"
+
+# Nach Bundesland filtern
+curl "http://localhost:8080/api/immobilies?bundesland=/api/bundeslands/1"
+```
+
+## Fehler-Codes
+
+| Status Code | Bedeutung |
+|-------------|-----------|
+| 200 | OK - Erfolgreiche Anfrage |
+| 201 | Created - Ressource erstellt |
+| 204 | No Content - Erfolgreich gelöscht |
+| 400 | Bad Request - Ungültige Daten |
+| 401 | Unauthorized - Authentifizierung fehlgeschlagen |
+| 403 | Forbidden - Keine Berechtigung |
+| 404 | Not Found - Ressource nicht gefunden |
+| 500 | Internal Server Error - Server-Fehler |
+
+---
+
+**Weitere Informationen:**
+- [Features](features.md) - Funktionsübersicht
+- [Technical](technical.md) - Datenbank-Schema & Architektur
+
+[← Zurück zur Hauptseite](../README.md)