Versioning and compatibility - JobHandy Developers

The current public API version is part of the base URL:

https://api.jobhandy.io/v1

The OpenAPI document identifies the JobHandy Public API as version 1.0.0 and uses OpenAPI 3.1.0.

The updated order and division schemas are documented within API version 1.0.0. The production base URL remains https://api.jobhandy.io/v1; no /v2 endpoint or separate specification revision is introduced.

Change classification

Change	Expected handling
New optional response property	Compatible; clients should ignore unknown properties
New endpoint or schema	Compatible addition
New optional request parameter	Compatible addition
New enum value in a response	Treat as additive; log unknown value for mapping review
Existing field becomes required in a request	Breaking unless a documented default/omission behavior preserves compatibility
Field removed or renamed	Breaking
Meaning of an existing value changes	Breaking
New required authentication behavior	Breaking

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 August 28, 2026