## Infosnow Public Widget V2 – explizite Source-Freigabe `GET /v1/public/infosnow/widget-v2.php?widget=` nutzt den geprüften Data-Layer-V2-Public-Reader. Aktuell ausschliesslich `light-ride`, keine freien Quellidentitäten, keine internen Remarks. Public-Rate-Limit, enge Parameter, TTL begrenzt durch Full-Import-Freshness; unbekannte Slugs 404, fehlende/stale Source 503. Ein Git-Merge ist **keine** Production-Freigabe. Consumer-Cutover erst nach manuellem Deploy und HTTP-Abnahme. ## Internal Infosnow Widget Source Catalog V2 `GET /v1/internal/infosnow/widget-source-catalog.php`: `internal:read`, exact source/season/resort scope, maximal 15 Ergebnisse pro Seite und maximal 400 Current-/Full-Import-Elemente je Scope. Ein einzelner autorisierter, begrenzter Source-Read prüft native Planperioden über den bestehenden Parser und liefert nur Objektname/ID/Gruppe, Planqualifikation und Status. **Keine neue Public-API, kein Public-StatusRemarks, kein Provider-Cutover.** [Contract und Sicherheitsgrenzen](INFOSNOW_WIDGET_SOURCE_CATALOG_V2.md). Neuer Endpoint erst nach autorisiertem manuellem Data-Layer-Release und geschütztem HTTP-Readback nutzbar. ## Infosnow Planned Schedule Internal V1 (AP1) Die neue Route `/v1/internal/infosnow/planned-schedule.php` ist **nur** für authentifizierte Backend-Consumer bestimmt (`internal:read`, keine Browser-CORS-Freigabe). Sie liefert source-native Planfenster und geplante Tage aus der bereits bestehenden Full-Import-Zeile, nicht aktuelle Ist-Statuswerte, bestätigte Erlebnistermine oder ein Public/Partner-Datenprodukt. Das minimierte Gäste-Produkt und der Pimcore-Widget-Cutover benötigen einen separaten Contract. Dokumentation und Release-Gates: `docs/INFOSNOW_PLANNED_SCHEDULE_DATA_PRODUCT_V1.md`. ## Kassenzeiten Type2 – intern nur Source-Kandidaten (keine Public-Freigabe) Der bestehende interne `GET /v1/internal/infosnow/operational-current-v2.php?resort_id=57&season=winter&view=cash_desk_candidates_v1` projiziert **nur** private validierte Type-2-Current-Cache-Daten. `internal:read`, GET-only, Rate-Limit, No-CORS, `private,no-store` und Noindex bleiben unverändert. Keine neue Route, keine Browser-Credentials, kein direktes Provider-SDK für Kassenzeiten. `divers` und `type` sind vor einem Type1/2-Paritätsbeleg keine autoritative Kassenklassifikation; es ist kein Gaststatus-/BFF-Feldvertrag. [Fachliche Gates](INFOSNOW_TYPE2_CASH_DESK_CANDIDATES_V1.md). ## Map Studio / Infosnow Type-2 Current V1 (intern, Code-only) Der **bestehende** interne `GET /v1/internal/infosnow/operational-current-v2.php` erlaubt optional `view=map_studio_v1` ausschliesslich mit exaktem Resort 57/67 und Saison summer/winter. Serverseitig authentifiziertes `internal:read`, gleiche GET-/Rate-Limit-/No-CORS-/No-Store-Grenzen; keine zweite Route, kein direkter Provider-Zugriff und kein Public/Partner-Vertrag. Source-native Gruppen/IDs/Status/Condition/Betriebszeiten und Last-Good-Aktualitaet werden nur intern bereitgestellt. Mapping- und Consumer-Go bleiben gesperrt; Type2 Source ist OFF. [Fachvertrag](INFOSNOW_TYPE2_MAP_STUDIO_CURRENT_V1.md). # API Usage Guide ## Architekturentscheid: Internal first. Public only by explicit decision. Neue Datenprodukte werden standardmässig als geschützte serverseitige Reads konzipiert. First-Party-Frontends erhalten nur die separat geprüften Gäste-Felder über vorhandene Backends oder schlanke BFFs. Öffentliche, Partner- und Open-Data-Ausgaben benötigen jeweils einen expliziten fachlichen und rechtlichen Freigabeentscheid. Bestehende Public-APIs sind bis zur belegten Consumer-Inventur und einem kontrollierten Cutover unverändert weiterzuführen. **Hinweis zur Freigabe:** Die öffentliche API-Dokumentation beschreibt nur ausdrücklich freigegebene Schnittstellen; interne Architektur- und Migrationsentscheide bleiben im privaten Repository. Die Anzahl externer produktiver Consumer ist noch nicht anhand von Laufzeit-Logs verifiziert. Browser-Origins und CORS sind keine Authentifizierung. Dieses Dokument beschreibt die wichtigsten Nutzungsregeln für Partner:innen, die die API von W.O.W. Lenzerheide verwenden. API-Basis: ```txt https://api.lenzerheide.swiss ``` Developer Portal: ```txt https://docs.lenzerheide.swiss ``` ## API-Bereiche | Bereich | Zugriff | Zweck | |---|---|---| | Public API | ohne API-Key | öffentlich freigegebene Daten | | Partner API | API-Key + Scope | freigegebene Partnerdaten | Die Swagger UI trennt beide Bereiche: ```txt Partner API · API-Key Public API · ohne API-Key ``` ## Zugriff und Authentifizierung Partner-Endpunkte benötigen einen API-Key. Empfohlener Header: ```txt X-API-Key: YOUR_API_KEY ``` Alternative: ```txt Authorization: Bearer YOUR_API_KEY ``` API-Keys sind vertraulich und dürfen nicht in Browser-JavaScript, Mobile Apps, öffentlichen Repositories, Tickets oder Screenshots veröffentlicht werden. ## Scopes und Least Privilege API-Keys werden auf notwendige Datenbereiche begrenzt. | Scope | Datenbereich | |---|---| | `traffic:read` | Partner-Verkehrsdaten | | `weather:read` | Partner-Wetterdaten | Ein fehlender Scope führt zu: ```txt 403 Forbidden ``` Grundsatz: Ein Partner-Key erhält nur die Scopes, die für den vereinbarten Use Case nötig sind. ## Rate Limits | Zugriff | Limit | |---|---:| | Public API | Standard: 120 Requests pro Minute und 20 000 pro Tag, pro IP-Adresse | | Partner API | Standard: 60 Requests pro Minute und 5 000 pro Tag, pro API-Key | Diese Werte sind die Code-Standards bei **aktiviertem** Rate Limiting und koennen in der privaten Runtime-Konfiguration ueberschrieben werden. Die Origin wird fuer CORS geprueft, ist aber kein separater Public-Rate-Limit-Schluessel. Bei Erreichen des Limits antwortet die API mit: ```txt 429 Too Many Requests ``` Empfehlung: - Antworten sinnvoll cachen. - Keine unnötig kurzen Polling-Intervalle verwenden. - Bei `429` Requests verzögern und erneut versuchen. - Bei `503` später erneut versuchen. ## Caching und Aktualität Partner:innen dürfen Responses cachen, sofern Aktualität und Use Case passen. | Datentyp | Empfehlung | |---|---| | Status | kurz cachen, z. B. 1 Minute | | Traffic | kurz cachen, z. B. 1 bis 5 Minuten | | Weather | je nach Anzeige 5 bis 30 Minuten | | Lift Status | kurz cachen und Freshness beachten | `meta.generatedAt`, fachliche Zeitstempel und vorhandene Freshness-Felder sollen für Aktualitätshinweise verwendet werden. ## Fehlerbehandlung | Status | Bedeutung | Empfehlung | |---:|---|---| | 400 | Fehlerhafte Anfrage | Parameter prüfen | | 401 | Nicht autorisiert | API-Key prüfen | | 403 | Kein Zugriff | Scope oder Freigabe prüfen | | 429 | Rate Limit erreicht | Request verzögern | | 500 | Serverfehler | später erneut versuchen | | 503 | Service temporär nicht verfügbar | später erneut versuchen | ## Versionierung Die aktuelle API-Version ist: ```txt /v1/... ``` Innerhalb von `/v1` können neue Felder ergänzt werden. Bestehende Integrationen sollten unbekannte Felder ignorieren können. Breaking Changes werden nicht stillschweigend innerhalb von `/v1` eingeführt. ## Datenverwendung Partner:innen dürfen die API-Daten für den vereinbarten Zweck verwenden. Wichtig: - Daten nicht irreführend darstellen. - Quellen- und Aktualitätshinweise berücksichtigen. - API-Daten nicht als alleinige Grundlage für sicherheitskritische Entscheidungen verwenden. - Daten nicht an unberechtigte Dritte weitergeben, sofern dies nicht vereinbart ist. ## Datenschutz und Governance Public- und Partner-API geben nur fachlich freigegebene Daten aus. Die öffentlich dokumentierten Endpunkte sind nicht für personenbezogene Profile oder Bewegungsprofile vorgesehen. Partner:innen dürfen API-Daten nicht mit eigenen Daten so kombinieren, dass daraus ohne passende Rechtsgrundlage personenbezogene Profile, Bewegungsprofile oder Kontrollsysteme entstehen. Für neue Datenbereiche gilt deny-by-default: Eine Quelle oder ein Feld wird erst öffentlich oder für Partner:innen dokumentiert, wenn Freigabe, Zweck, Datenqualität, Datenschutz und Nutzungsrechte geklärt sind. ## Technische Empfehlungen - Partner-Endpunkte serverseitig aufrufen. - API-Key in einer geschützten Server-Konfiguration oder Secret-Verwaltung speichern. - Timeouts und Retry-Logik einbauen. - `429` und `503` sauber behandeln. - Responses cachen, wenn die Aktualität für den Use Case ausreicht. - Fehlgeschlagene Requests monitoren. - Unbekannte Felder in Responses ignorieren. - Zugriffsrechte und aktive Keys regelmässig überprüfen. ## Zugang beantragen API-Zugriff wird pro Partner:in und Use Case freigegeben. Für die Freigabe werden in der Regel benötigt: ```txt Partnerorganisation technischer Kontakt geplanter Use Case benötigte Datenbereiche / Scopes geplante Anwendung / Domain ungefähre Request-Frequenz ``` ## W.O.W. API Contract V1 – AP4-Vorbereitung Neue Datenprodukt-APIs koennen nach separater fachlicher und technischer Freigabe das standardisierte Response-Format (data/meta), OpenAPI 3.1, JSON Schema 2020-12 und RFC-9457-Problemtypen nutzen. Im Data Layer sind die gemeinsamen Bausteine vorerst nur als **opt-in, nicht eingebundene Library** vorhanden. Bestehende /v1-Endpunkte liefern weiterhin ihre bisherigen Response- und Fehlerformate. Die gemeinsame API-Bibliothek ersetzt weder Rechtepruefung, Authentifizierung, CORS, Rate Limiting noch die fachliche Datenfreigabe. Details: docs/API_CONTRACT_AP4.md. Ein Public-/Partner- oder Consumer-Cutover erfordert einen separaten Release- und Migrationsentscheid. ## AP5 · Neues Wetter-V2-Datenprodukt (noch gesperrt) Ein separates, W.O.W.-API-Contract-V1-konformes Referenzprodukt für MeteoSwiss Daily Forecast wird kontrolliert vorbereitet. Der API-V2-Vertrag bleibt **nicht freigegeben** und erscheint bis zum genehmigten Release weder im Public Swagger noch im Developer Portal. Die produktive V1-Wetter-API, ihre Fehlerformate, Consumer, Berechtigungen und Nutzungsregeln bleiben unverändert. Für denselben MeteoSwiss-Public-Zweck werden die bestehenden V1-Source-/Privacy-/Nutzungsrechts-Nachweise **referenziert und nicht neu beantragt**. AP5 prüft nur konkrete V2-Deltas (insbesondere ungerundete Temperaturpräzision, Freshness, HTTP/Consumer) sowie die eigenständige Production-Freigabe. Die maschinenlesbare Evidence steht unter `docs/contracts/weather_current_v2_existing_scope_evidence_v1.json`; Details unter `docs/API_CONTRACT_AP5.md`. Keine neuen Runtime- oder Public-Rechte durch diese Dokumentation. ## Weiterführende Dokumentation ```txt https://docs.lenzerheide.swiss/getting-started.md https://docs.lenzerheide.swiss/api-reference.md https://docs.lenzerheide.swiss/data-model.md https://docs.lenzerheide.swiss/use-cases.md https://docs.lenzerheide.swiss/api-changelog.md ```