Zum Hauptinhalt springen

​
Migration von 1.0.0 auf 2.0.0

Prüfen Sie mindestens Incident-Erstellung mit active, approved und ohne aktiven Vertrag sowie Employee-Patches mit beiden blocked-Werten, gemischten Profil-/Sperrfeldern und vollständig weggelassenem blocked. Führen Sie die Prüfungen für Dry Run und reale Schreibvorgänge in einem dafür freigegebenen Testprozess aus. Bestehende Vorfälle müssen weiterhin bearbeitbar bleiben.

​
API 2.0.0: Aktiver Vertrag erforderlich

POST /incidents erfordert einen Vertrag mit Status active. Der Status approved reicht nicht aus. Ohne aktiven Vertrag scheitert die Anfrage mit HTTP 422 und EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, auch bei dryRun=true; es wird kein Vorfall erstellt. Klären Sie den Vertragsstatus über den zuständigen Fachprozess, bevor Sie eine neue Anfrage mit neuer X-Request-ID senden. Bestehende Vorfälle bleiben unter ihren bisherigen Lebenszyklus- und Feldbeschränkungen bearbeitbar. Die neue Voraussetzung gilt für das Erstellen. Die Voraussetzung der Mitarbeiteraktivierung bleibt separat dokumentiert; eine Reihenfolge der Validierungsfehler ist nicht festgelegt.

​
API 2.0.0: Sperränderungen bei aktiven Verträgen

Bei PATCH /employees/{id} verbietet ein aktiver Vertrag sowohl blocked: true als auch blocked: false. Enthält die Anfrage blocked, lehnt die API den gesamten Patch mit HTTP 422 und EMPLOYEE_HAS_ACTIVE_CONTRACT ab, auch bei dryRun=true. Andere Felder dieser abgelehnten Anfrage werden nicht übernommen. Auch das erneute Senden des bereits gespeicherten blocked-Werts ist unzulässig. Für reine Profiländerungen lassen Sie blocked vollständig weg. Konfigurieren Sie Serialisierung und Synchronisationsmapping so, dass blocked: false nicht als Standardwert hinzugefügt wird. Beispiel:
Wiederholen Sie einen unveränderten abgelehnten Patch nicht. Klären Sie den Sperrauftrag über den zuständigen Fachprozess oder senden Sie für eine unabhängig beabsichtigte Profiländerung einen neuen Patch ausschließlich mit den gewünschten unterstützten Profilfeldern. Ein erfolgreicher Dry Run reserviert den Vertragsstatus nicht; behandeln Sie dieselbe Validierung beim realen Schreibvorgang. Die Vertragsversion ist 2.0.0. Die weiterhin dokumentierte produktive Basis-URL lautet:
Das OpenAPI-Dokument bezeichnet die JobHandy Public API als Version 2.0.0 und verwendet OpenAPI 3.1.0.
Version 2.0.0 enthält inkompatible Verhaltensänderungen. Ein reiner Schema-Diff oder die Neuerzeugung eines Clients reicht für die Migration nicht aus. Der dokumentierte URL-Pfad bleibt /v1.

​
Änderungsklassifizierung

​
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 auf Migrationshinweise.

​
Ablauf eines Vertragsupdates

​
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.
Zuletzt geändert am 20. Oktober 2026