# Use Cases

Diese Seite zeigt typische Einsatzmöglichkeiten der Public und Partner API von W.O.W. Lenzerheide.

## Website Widget

Ziel: Aktuelle Informationen auf einer Partner-Website anzeigen.

Geeignete API:

```txt
Public API
```

Typische Endpunkte:

```txt
GET /v1/public/traffic/status.php
GET /v1/public/weather/current.php
GET /v1/public/weather/forecast.php
GET /v1/public/lifts/current.php
```

Empfehlung:

- Clientseitig nur Public-Endpunkte verwenden.
- Responses für kurze Zeit cachen.
- Aktualität sichtbar machen, z. B. über `meta.generatedAt`.
- Weather `current.php` als Wetter-Tageswert interpretieren. Bei `dataType=forecast` handelt es sich nicht um eine Echtzeit-Stationsmessung.
- Bei Weather für Provenance `source`, `sourceCreatedAt` und `capturedAt` verwenden. `observedAt` ist dort nur ein Legacy-Alias.
- Near-Live-Daten nie als garantiert aktuell darstellen, wenn `freshness` oder Zeitstempel auf veraltete Daten hinweisen.

## Partner Cockpit

Ziel: Freigegebene Daten in einem Partner-Cockpit oder internen System anzeigen.

Geeignete API:

```txt
Partner API
```

Typische Endpunkte:

```txt
GET /v1/partner/traffic/summary.php
GET /v1/partner/weather/summary.php
```

Empfehlung:

- Server-to-server integrieren.
- API-Key sicher speichern.
- Nur notwendige Scopes freigeben.
- Fehler und Rate Limits monitoren.
- Nicht verfügbare MeteoSwiss Daily-Felder als `null` behandeln und nicht lokal mit Ersatzwerten auffüllen.

## Informationsscreen

Ziel: Aktuelle Informationen auf Screens anzeigen, z. B. in Hotel, Betrieb oder Infopoint.

Geeignete API:

```txt
Public API oder Partner API
```

Entscheidung:

| Bedarf | Empfehlung |
|---|---|
| einfache öffentliche Anzeige | Public API |
| erweiterte Partnerdaten | Partner API |

Empfehlung:

- Polling-Intervall bewusst wählen.
- Bei `503` letzte bekannte Daten nur mit Aktualitätshinweis anzeigen.
- Zeitstempel der letzten Aktualisierung zeigen.
- Bei Wetter klar zwischen Forecast-Zeitpunkt und Data-Layer-Erfassungszeitpunkt unterscheiden.

## App oder Backend Integration

Ziel: Daten in einer App oder einem Backend weiterverarbeiten.

Geeignete API:

```txt
Public API oder Partner API
```

Empfehlung:

- Public-Daten können direkt genutzt werden, wenn der Use Case keinen geschützten Datenbereich benötigt.
- API-Key nie direkt in eine Mobile App einbauen.
- Für Partner-Endpunkte ein eigenes Backend als Proxy nutzen.
- Responses cachen und normalisieren.
- Neue Felder innerhalb von `/v1` tolerieren und unbekannte Felder ignorieren.

## Reporting und Planung

Ziel: Freigegebene Daten in Planungs- oder Reportingprozessen verwenden.

Geeignete API:

```txt
Partner API
```

Empfehlung:

- Nur vereinbarte Datenbereiche verwenden.
- Datenstand und Source-Referenz dokumentieren.
- API-Daten nicht ohne fachlichen Kontext interpretieren.
- Forecast-Werte nicht nachträglich als gemessene Ist-Werte umdeuten.

## Auswahlhilfe

| Frage | API |
|---|---|
| Soll die Information öffentlich auf einer Website erscheinen? | Public API |
| Braucht der Use Case einen API-Key? | Partner API |
| Werden geschützte Daten in einem internen Partner-System verarbeitet? | Partner API |
| Soll der Request direkt aus dem Browser kommen? | Public API |
| Soll ein geschützter Datenbereich genutzt werden? | Partner API |