Zum Inhalt springen

Open Beta – hilf uns beim Testen! Alle Inserate sind nur Beispiele.

WOHNO

Versionierung & Deprecation-Policy

Wie die WOHNO-REST-API versioniert wird, warum Änderungen additiv bleiben und wie Deprecations und DTO-Versionen gehandhabt werden.

Diese Seite dokumentiert, wie sich die WOHNO-REST-API weiterentwickelt, damit du mit Vertrauen integrieren kannst. Die Kurzfassung: Die API bleibt auf v1, Änderungen sind additiv, und alles Breaking durchläuft eine angekündigte Deprecation mit großzügigem Sunset-Fenster.

API-Version: v1

Alle Endpoints liegen unter einem einzigen versionierten Basis-Pfad:

https://wohno.de/api/v1

Wir beabsichtigen, die API auf absehbare Zeit auf v1 zu halten. Neue Ressourcen, Endpoints, Felder und Scopes werden innerhalb von v1 ergänzt, statt in eine neue Major-Version ausgelagert zu werden.

Nur additive Änderungen

Innerhalb von v1 ist jede Änderung additiv und rückwärtskompatibel:

  • Neue Endpoints und Ressourcen können jederzeit hinzukommen.
  • Neue optionale Felder können bestehenden Antworten hinzugefügt werden.
  • Neue Scopes können für neue Funktionen eingeführt werden.

Diese Änderungen brechen niemals eine konforme Integration, also solltest du deine Clients defensiv schreiben:

  • Ignoriere unbekannte Felder in Antworten, statt an ihnen zu scheitern.
  • Nimm nicht an, dass die Menge der Objekt-Keys fix ist — behandle Antworten als vorwärtskompatibel.
  • Fordere nur die Scopes an, die du brauchst; neue Scopes sind opt-in.

Jede additive Änderung wird im API-Changelog festgehalten.

Breaking Changes & der Deprecation-Prozess

Eine Änderung, die einen konformen Client brechen könnte (Entfernen eines Felds oder Endpoints, Ändern eines Typs oder Defaults, Verschärfen der Validierung), ist ein Breaking Change. Breaking Changes werden, wo immer möglich, vermieden. Wenn unvermeidbar, durchlaufen sie einen dokumentierten Deprecation-Prozess, statt still zu landen:

  1. Ankündigung — die Änderung wird im Changelog veröffentlicht, dem kanonischen Informationskanal für die API-Entwicklung.
  2. Sunset-Fenster — betroffene Endpoints werden in der OpenAPI-Spec als deprecated: true markiert und liefern einen Sunset-HTTP-Header mit dem Datum, ab dem das alte Verhalten entfernt wird. Das Standardfenster beträgt mindestens 90 Tage.
  3. Direkte Benachrichtigung — betroffene Key-besitzende Organisationen erhalten eine In-App-Benachrichtigung, sodass du dich nicht allein auf das Pollen des Changelogs verlässt.
  4. Entfernung — erst nach Ablauf des Sunset-Datums wird das alte Verhalten entfernt.

Ist ein Breaking Change als Security-Hotfix erforderlich, gilt eine beschleunigte ("emergency") Deprecation: Die Änderung geht sofort live, mit sofortiger Benachrichtigung und einem Changelog-Eintrag, der Grund und Auswirkung dokumentiert.

DTO-Versionierung (*_DTO_VERSION)

Antwort-Bodies werden aus expliziten, whitelisteten Data-Transfer-Objects (*PublicDto) gebaut — niemals aus rohen Datenbankzeilen. Jedes DTO trägt eine Versionskonstante (*_DTO_VERSION). Wenn sich die Form eines DTOs ändert, erhöhen wir seine Version. Da die DTO-Version in den ETag cachebarer GET-Antworten einfließt, invalidiert das Erhöhen veraltete Caches, sodass Clients und Intermediäre die neue Form abrufen statt einen veralteten Body auszuliefern.

DTO-Versions-Erhöhungen sind additiv (neue optionale Felder). Sie stellen für sich genommen keinen Breaking Change dar — sie existieren genau dafür, dass die API die Form eines Payloads weiterentwickeln kann, während das Conditional-Request-Caching korrekt bleibt.

Auf dem Laufenden bleiben

Das API-Changelog ist die zentrale Quelle der Wahrheit für jede API-Änderung — neue Endpoints, neue Scopes, Deprecations und Sunset-Daten. Bei Breaking Changes werden Key-besitzende Organisationen zusätzlich In-App benachrichtigt. Wir empfehlen, das Changelog zu prüfen, bevor du eine neu gelistete (insbesondere dark-shipped oder nicht-GA) Ressource einsetzt.