> ## 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.

# Versioning and compatibility

> Understand URL versioning, additive changes, breaking changes, enum evolution, and contract-update responsibilities.

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

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

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

<Info>
  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.
</Info>

## 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](/operations/changelog) for migration notes.

## Contract update flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[New OpenAPI release] --> B[Automated diff]
    B --> C{Breaking or behavior change?}
    C -- No --> D[Regenerate or validate client]
    C -- Yes --> E[Plan migration and testing]
    D --> F[Acceptance tests]
    E --> F
    F --> G[Deploy client]
    G --> H[Record adopted contract version]
```

## 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.