> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versionierung und Kompatibilität

> Verstehen Sie URL-Versionierung, additive Änderungen, Breaking Changes, Enum-Erweiterungen und Verantwortlichkeiten bei Vertragsupdates.

Die aktuelle öffentliche API-Version ist Bestandteil der Basis-URL:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.jobhandy.io/v1
```

Das OpenAPI-Dokument bezeichnet die JobHandy Public API als Version `1.0.0` und verwendet OpenAPI `3.1.0`.

<Info>
  Die aktualisierten Order- und Division-Schemas werden innerhalb der API-Version `1.0.0` dokumentiert. Die produktive Basis-URL bleibt `https://api.jobhandy.io/v1`; ein `/v2`-Endpoint oder eine separate Spezifikationsrevision wird nicht eingeführt.
</Info>

## Änderungsklassifizierung

| Änderung                                            | Erwartete Behandlung                                                                                |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Neue optionale Response-Eigenschaft                 | Kompatibel; Clients müssen unbekannte Eigenschaften ignorieren                                      |
| Neuer Endpoint oder neues Schema                    | Kompatible Erweiterung                                                                              |
| Neuer optionaler Request-Parameter                  | Kompatible Erweiterung                                                                              |
| Neuer Enum-Wert in einer Response                   | Als additiv behandeln; unbekannten Wert zur Mapping-Prüfung protokollieren                          |
| Vorhandenes Feld wird in einem Request erforderlich | Breaking, sofern dokumentiertes Standard- oder Auslassungsverhalten die Kompatibilität nicht erhält |
| Feld wird entfernt oder umbenannt                   | Breaking                                                                                            |
| Bedeutung eines vorhandenen Werts ändert sich       | Breaking                                                                                            |
| Neue verpflichtende Authentifizierungsanforderung   | Breaking                                                                                            |

## Regeln für Client-Design

* Verwenden Sie keine strikte Response-Deserialisierung, die unbekannte Eigenschaften ablehnt.
* Gehen Sie nicht davon aus, dass eine Enum-Liste niemals erweitert wird.
* Senden Sie ausschließlich dokumentierte Request-Eigenschaften, da Request-Schemas geschlossen sind.
* Pinnen und archivieren Sie die OpenAPI-Datei, mit der der Client erzeugt oder validiert wurde.
* Vergleichen Sie jeden neuen Vertrag vor dem Deployment mit der gepinnten Version.
* Prüfen Sie den [Changelog](/de/operations/changelog) auf Migrationshinweise.

## Ablauf eines Vertragsupdates

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Neue OpenAPI-Version] --> B[Automatisierter Diff]
    B --> C{Breaking Change oder Verhaltensänderung?}
    C -- Nein --> D[Client neu erzeugen oder validieren]
    C -- Ja --> E[Migration und Tests planen]
    D --> F[Abnahmetests]
    E --> F
    F --> G[Client bereitstellen]
    G --> H[Übernommene Vertragsversion dokumentieren]
```

## Deprecation

Eine zukünftige Deprecation muss vor der Entfernung über den öffentlichen Changelog und eine Migrationsanleitung kommuniziert werden. Verlassen Sie sich nicht auf einen undokumentierten Endpoint oder ein undokumentiertes Feld, nur weil es in einer internen Umgebung sichtbar ist.