immorechner/docs/api.md

# 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)