Workhuman Contract-Driven Adapter Patterns

Overview

Create a narrow, testable boundary around documented tenant capabilities while keeping vendor transport, business policy, and systems of record separate.

Prerequisites

• A current customer-authorized API schema, managed-connector mapping, or integration specification
• Defined operations, data classifications, owners, and compatibility window
• Synthetic fixtures for all supported results and failures

Tool Discipline

Use Read, Glob, and Grep to inspect contracts and consumers, WebFetch for current first-party context, and Write or Edit for types, adapter code, tests, and redacted receipts.

Current Contract

Workhuman describes an open API but does not publish a universal public SDK or stable route catalogue on the cited public pages. Generate or hand-build only from customer-authorized artifacts and pin the artifact identity.

Authentication

Inject the documented authorization provider at runtime. Keep secret acquisition outside the adapter, prevent cross-tenant reuse, and redact authorization and workforce data from errors.

Instructions

1. Inventory required operations and map each to an exact authorized contract section and owning system.
2. Pin the schema or mapping fingerprint, environment, tenant, acquisition date, and compatibility promise.
3. Generate types when the artifact supports it; otherwise define minimal request and response types without speculative fields.
4. Separate transport, authentication, serialization, retry, idempotency, policy, and business orchestration.
5. Preserve vendor status and safe correlation fields in a normalized error union.
6. Validate response envelopes, tolerate documented optional fields, and reject unsafe type coercion.
7. Test duplicates, partial application, timeouts, throttling, revoked authorization, schema drift, and retry eligibility.
8. Expose only the operations required by the approved workflow and document deprecation ownership.

Approval Boundaries

Do not add undocumented operations, generate from untrusted schemas, publish customer artifacts, or execute tenant writes while building the adapter.

Output

Return the pinned contract identity, operation map, typed boundary, auth injection point, error model, fixture coverage, compatibility policy, and unresolved fields.

Error Handling

Example

A redacted completion receipt might look like this:

artifact=customer-openapi@sha256:...; operations=3; auth=injected; fixtures=14; unknown-fields=tolerated; ambiguous-writes=blocked

Resources

• Workhuman integrations and open API
• Workhuman security and privacy

Next Steps

Use the adapter in the local and CI lanes before proposing a canary tenant deployment.