API contract workflow

The API contract is the interface between Anis's track and Imad's track. One rule holds it together: no operation is implemented or consumed before it exists in packages/contracts on dev. The mock server lets the apps be built against the contract while the server implementation is still being written (ADR-002).

• SRV-03 writes contract v1 — every V1 operation, the OpenAPI export and the mock server — and reaches the milestone API contract v1 published (OpenAPI + mock server). Imad reviews it as the first consumer.
• MOB-03 generates hoco_api from that document, with a regeneration script, the Prism workflow and a pinned contract version.
• SRV-29 repeats the loop for the V2 operations, so V2 mobile work starts against the mock too.

After contract v1, every change follows the loop below, however small.

Where the contract livesCopy Anchor Link

The loopCopy Anchor Link

The description of a contract PR:

**Operations:** delegate.visits.arrive (changed: response adds `distanceMeters`), delegate.visits.start (changed: accepts an optional `note`)
**Class:** additive — contract 1.4.0 → 1.5.0
**Consumers:** DA-10 (MDA-03, MDA-05), BO-23 (DSH-08)
**New error codes:** none
**Examples:** updated for both responses

Mock serverCopy Anchor Link

Prism serves the OpenAPI document as a mock API, on the developer's machine:

# in hoco — the latest contract on your branch (regenerate it with pnpm openapi:export)
pnpm mock    # prism mock … --port 4010 --dynamic --cors

# in hoco-mobile — the pinned copy (the path is set in MOB-03)
npx @stoplight/prism-cli mock packages/hoco_api/openapi/hoco-v1.json --port 4010

# Android emulator: http://10.0.2.2:4010 · a phone on the same Wi-Fi: http://<laptop-ip>:4010

• Dynamic mode (--dynamic, what pnpm mock runs) generates data from the schemas. Response objects are closed (additionalProperties: false), so the generated data has exactly the documented fields. Contract v1.0.0 has no response examples yet; until they land, use dynamic mode.
• Static mode (without --dynamic) returns the response example; contract PRs add examples operation by operation.
• Error states: send Prefer: code=422 (or Prefer: example=<name>) to get the declared error example and build the error screens.
• Prism also validates the app's requests against the document: a request Prism rejects is a client bug to fix before integration. Prism's own validation answers are not HOCO's error envelope — build error UIs from the declared error examples, not from Prism's validation messages.

The Next apps do not need the mock: they live in the same repository as the server and run against it locally.

Additive and breaking changesCopy Anchor Link

A breaking need is shipped as an addition plus a deprecation, never in place. /v2 is reserved for a wholesale redesign and is not planned: the V2 product scope is additive and stays in /v1.

DeprecationCopy Anchor Link

• The route or field is marked deprecated in the contract. It appears as deprecated in the OpenAPI document, and the generated Dart code flags it.
• The server answers deprecated operations with Deprecation (RFC 9745) and Sunset (RFC 8594) headers and a link to the page:

Deprecation: @1798761600
Sunset: Fri, 31 Dec 2027 23:59:59 GMT
Link: <https://{docs-site}/docs/srs/api/orders#orderslist>; rel="deprecation"

• Removal needs all three conditions:
  1. at least two releases of each affected app have reached the track the users are on (closed track during the pilot, production after) without using the deprecated item;
  2. the minimum supported version of each affected app (BO-66) has been raised above the last version that uses it;
  3. the server logs (which carry X-App-Version) show no call to it for 14 days.
• The back-office and the reseller web are deployed with the server, so they migrate in the same release; the window exists for the mobile apps.

VersioningCopy Anchor Link

Assumption — the export currently takes info.version from apps/server/package.json. SRV-03 switches it to the version of @hoco/contracts, bumped in each contract PR, so the contract version moves only when the contract does.

Error codesCopy Anchor Link

• Every error an operation can return is declared in the contract with its HTTP status and details shape, and listed in the error registry.
• Codes are UPPER_SNAKE_CASE and stable forever: never renamed, never reused for another meaning. A retired code stays documented as retired.
• A new code arrives in one PR with: the contract declaration, the registry row (status, meaning, details, operations), the server message in French with ar and en keys, and an example. Imad adds the app mapping when he regenerates.
• Clients branch on code — never on message, never on the status alone.
• NOT_IMPLEMENTED (501) exists on staging only. The release checklist verifies that no contracted operation of the release still answers it.

Keeping the reference pages in syncCopy Anchor Link

• Once SRV-03 lands, the OpenAPI document is authoritative. endpoints.json and the API reference pages describe it for people.
• The contract PR updates, in the same PR: the operation in endpoints.json (op id, method, path, auth, permission, apps, release, requirements); its section on the API page (request, response example, errors, rules), under the anchor of its op id (cart.checkout → #cartcheckout); the error registry.
• CI (added with SRV-03) compares the op ids of the exported document with endpoints.json and fails when an operation is missing on either side.
• When a page and the document disagree, the document wins. The page is fixed in a docs(contracts): … commit.
• Scalar (/reference, local and staging) renders the same document, so it is always in sync.

Contract changelogCopy Anchor Link

Newest first. One entry per merged contract PR, in the same PR. Imad reads this table before each regeneration.

New entries follow this template:

| `1.5.0` | SRV-21 · #48 | delegate.visits.arrive returns `distanceMeters`; delegate.visits.start accepts an optional `note` | Additive | Regenerate; show the distance on DA-10 |