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

# Tooling and OpenAPI

> Import the OpenAPI contract into API clients, generate typed clients, validate requests, and control contract updates.

The OpenAPI 3.1 document is the authoritative machine-readable contract for the JobHandy Public API.

<Columns cols={2}>
  <Card title="OpenAPI JSON" icon="braces" href="https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.json" arrow="true">
    Recommended for tooling that consumes JSON directly.
  </Card>

  <Card title="OpenAPI YAML" icon="file-code" href="https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.yaml" arrow="true">
    Semantically equivalent human-readable representation.
  </Card>
</Columns>

## Import into an API client

### Postman or Insomnia

1. Download the JSON or YAML file.
2. Import it as an OpenAPI specification.
3. Configure `https://api.jobhandy.io/v1` as the server if the client does not select it automatically.
4. Store `X-API-Key` in the client's protected environment, not in a shared collection export.
5. Add `X-Tenant-ID` only where needed.
6. Disable or remove example secrets before sharing the workspace.

## Generate a client

Example with OpenAPI Generator:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @openapitools/openapi-generator-cli generate \
  -i jobhandy-public-api.openapi.json \
  -g typescript-fetch \
  -o generated/jobhandy
```

Example for a C# client:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @openapitools/openapi-generator-cli generate \
  -i jobhandy-public-api.openapi.json \
  -g csharp \
  -o generated/jobhandy-csharp
```

Review generated code before production use. Generated clients do not automatically implement customer-specific secret loading, retry budgets, reconciliation, logging, or data-protection controls.

## Contract validation in CI

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Download pinned OpenAPI] --> B[Validate syntax and references]
    B --> C[Diff against adopted version]
    C --> D[Regenerate client or types]
    D --> E[Compile]
    E --> F[Run contract and integration tests]
    F --> G[Approve adoption]
```

Recommended checks:

* OpenAPI 3.1 validation succeeds
* all `$ref` values resolve
* `operationId` values remain unique
* generated code compiles
* examples conform to schemas
* no unexpected breaking changes appear
* the production server remains `https://api.jobhandy.io/v1`
* no development or stage host is introduced into customer configuration

## Pin the adopted contract

Archive the exact JSON or YAML file used by each client release. Record:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
client release
OpenAPI info.version
file checksum
adoption date
generator and configuration
breaking-change review result
```

Do not regenerate a production client automatically from an unreviewed remote file.