Skip to main content

Versioning & deprecation

The Partner API is versioned in the URL — every partner endpoint lives under the /v1 prefix (/v1/cooperatives, /v1/investors/...). This document is the canonical record of what's stable and what isn't.

When we introduce breaking changes, we move to a new URL prefix (/v2/...) and the /v1 paths are supported per the deprecation lifecycle below.

What we promise​

While the contract stays at v1, we will not:

  • Remove an endpoint.
  • Remove a field from a successful response.
  • Change the type of an existing response field.
  • Add a required request parameter.
  • Change a successful response status code.
  • Change the meaning of an existing error code.

We may, without notice:

  • Add a new endpoint, optional query parameter, or response field.
  • Add a new error code to an existing status. Default-handle by status; branch on code only when you intend to.
  • Change a description or summary in the OpenAPI spec.
  • Change the wire format of a field whose schema declares additionalProperties: true (for example, type_specific extension fields on CooperativeProjectResponse).

Treat unknown fields as forward-compatible — your client must not reject responses that contain fields it does not yet know about.

When we cut a new version​

A breaking change moves the path to a new prefix (/v2/...). Both the old and the new contract run side-by-side for at least 12 months:

PhaseTimingWhat happens
AnnouncementT+0New version available. Old endpoints unchanged.
Soft sunsetT+9 monthsSunset: <date> and Deprecation: true headers added to old-version responses. Email to partner technical contacts.
Hard sunsetT+12 monthsOld endpoints return 410 Gone with a Link: <new-url>; rel="successor-version" header.

Deprecation signals within a version​

For changes inside the current contract (e.g. an old query parameter superseded by a better one), we flag deprecations on the response:

Deprecation: Sun, 03 May 2026 12:00:00 GMT
Sunset: Mon, 03 May 2027 12:00:00 GMT
Link: <https://api.valueverde.de/v1/cooperatives>; rel="successor-version"

The OpenAPI spec marks the same operations and parameters with deprecated: true. The changelog lists every deprecation as it is introduced.