Skip to main content

​
Migration from 1.0.0 to 2.0.0

Cover incident creation with active, approved, and no active contract, plus employee patches with both blocked values, mixed profile/blocking fields, and fully omitted blocked. Cover dry-run and real-write behavior in an authorized test process. Existing incidents must remain editable.

​
API 2.0.0: active contract required

POST /incidents requires a contract with status active. Status approved is insufficient. Without an active contract, the request fails with HTTP 422 and EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, including when dryRun=true; no incident is created. Resolve the contract state through the responsible business process before submitting a new request with a new X-Request-ID. Existing incidents remain editable under their existing lifecycle and field restrictions. This new prerequisite applies to creation. The employee activation prerequisite remains documented separately; no precedence between validation errors is specified.

​
API 2.0.0: blocking changes and active contracts

For PATCH /employees/{id}, an active contract prohibits both blocked: true and blocked: false. If blocked is included, the API rejects the entire patch with HTTP 422 and EMPLOYEE_HAS_ACTIVE_CONTRACT, including when dryRun=true. Other fields in that rejected request are not applied. Sending the employee’s existing blocked value does not avoid this rule. For profile-only updates, omit blocked entirely. Configure serializers and synchronization mappings so they do not add blocked: false as a default. For example:
Do not retry an unchanged rejected patch. Resolve the blocking request through the responsible business process, or, for an independently intended profile update, send a new patch containing only the intended supported profile fields. A successful dry run does not reserve contract state; handle the same validation on the real write. The contract version is 2.0.0. The documented production base URL remains:
The OpenAPI document identifies the JobHandy Public API as version 2.0.0 and uses OpenAPI 3.1.0.
Version 2.0.0 introduces incompatible behavior changes. A schema-only diff or regenerated client is insufficient for migration. The documented URL path remains /v1.

​
Change classification

​
Client design rules

  • Do not use strict response deserialization that rejects unknown properties.
  • Do not assume an enum list can never grow.
  • Send only documented request properties because request schemas are closed.
  • Pin and archive the OpenAPI file used to generate or validate the client.
  • Compare each new contract against the pinned version before deployment.
  • Review the Changelog for migration notes.

​
Contract update flow

​
Deprecation

A future deprecation should be communicated through the public changelog and migration guidance before removal. Do not rely on an undocumented endpoint or field merely because it is observable in an internal environment.
Last modified on October 20, 2026