Skip to content

Open Beta – help us test! All listings are examples only.

WOHNO

Versioning & Deprecation Policy

How the WOHNO REST API is versioned, why changes stay additive, and how deprecations and DTO versions are handled.

This page documents how the WOHNO REST API evolves, so you can integrate with confidence. The short version: the API stays on v1, changes are additive, and anything breaking goes through an announced deprecation with a generous sunset window.

API version: v1

All endpoints live under a single versioned base path:

https://wohno.de/api/v1

We intend to keep the API on v1 for the foreseeable future. New resources, endpoints, fields and scopes are added within v1 rather than spun off into a new major version.

Additive changes only

Within v1, every change is additive and backward-compatible:

  • New endpoints and resources can appear at any time.
  • New optional fields can be added to existing responses.
  • New scopes can be introduced for new capabilities.

These changes never break a conforming integration, so you should write clients defensively:

  • Ignore unknown fields in responses rather than failing on them.
  • Don't assume the set of object keys is fixed — treat responses as forward-compatible.
  • Request only the scopes you need; new scopes are opt-in.

Every additive change is recorded in the API Changelog.

Breaking changes & the deprecation process

A change that could break a conforming client (removing a field or endpoint, changing a type or default, tightening validation) is a breaking change. Breaking changes are avoided wherever possible. When unavoidable, they go through a documented deprecation process rather than landing silently:

  1. Announcement — the change is published in the Changelog, which is the canonical information channel for API evolution.
  2. Sunset window — affected endpoints are marked deprecated: true in the OpenAPI spec and return a Sunset HTTP header indicating the date after which the old behaviour is removed. The standard window is at least 90 days.
  3. Direct notification — affected key-owning organizations receive an in-app notification, so you are not relying on polling the changelog alone.
  4. Removal — only after the sunset date passes is the old behaviour removed.

If a breaking change is required as a security hotfix, an expedited ("emergency") deprecation applies: the change ships immediately, with an immediate notification and a changelog entry documenting the reason and impact.

DTO versioning (*_DTO_VERSION)

Response bodies are built from explicit, whitelisted Data Transfer Objects (*PublicDto) — never raw database rows. Each DTO carries a version constant (*_DTO_VERSION). When a DTO's shape changes, we bump its version. Because the DTO version feeds into the ETag of cacheable GET responses, bumping it busts stale caches so clients and intermediaries fetch the new shape instead of serving an outdated cached body.

DTO-version bumps are additive (new optional fields). They do not, on their own, constitute a breaking change — they exist precisely so the API can evolve a payload's shape while keeping conditional-request caching correct.

Staying informed

The API Changelog is the single source of truth for every API change — new endpoints, new scopes, deprecations and sunset dates. For breaking changes, key-owning organizations are additionally notified in-app. We recommend reviewing the changelog before adopting any newly listed (especially dark-shipped or non-GA) resource.