5.5.2.7 Reconciliation
The Reconciliation domain of farm. One fact per real event, built from the evidence of every feed by versioned rules: resolved events and the evidence behind them, animal links, data issues that tell the farm what to fix at the source, and the rule sets and source reliability rankings. The system decides; there is no human review step, and this API changes nothing but the rules. It is one API, with its own contract and its own version.
5.5.2.7.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://farm.moonitoring.com/reconciliation/v1 |
reconciliation/v1/openapi.yaml |
The resources follow the data model. Read-only on facts; the only writes are rule sets, reliability rankings and a re-run, behind the proposed capability farm.reconciliation_rules.manage. Animal links are never created by hand.
5.5.2.7.2 Operations¶
Every operation names who calls it and the capability it checks (x-moonitoring-audience, x-moonitoring-capability in the contract); every capability is in the catalog of the data model (req 1002, 1006). Lists are paged by cursor, writes that create something carry an Idempotency-Key, errors are Problem Details.
| Operation | Request | Who | Capability |
|---|---|---|---|
| List resolved events | GET /organizations/{organization_id}/resolved-events |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| Read a resolved event with its evidence | GET /resolved-events/{resolved_event_id} |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| List a resolved event's revisions | GET /resolved-events/{resolved_event_id}/revisions |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| List animal links | GET /organizations/{organization_id}/animal-links |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| Read an animal link | GET /animal-links/{link_id} |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| List data issues | GET /organizations/{organization_id}/data-issues |
Organization users, staff or clients | farm.data_issues.read or farm.data_issues.read_all |
| List every data issue | GET /data-issues |
Staff | farm.data_issues.read_all |
| Read a data issue | GET /data-issues/{issue_id} |
Organization users, staff or clients | farm.data_issues.read or farm.data_issues.read_all |
| List rule sets | GET /rule-sets |
Organization users, staff or clients | none: any member of the Organization |
| Create a rule set version | POST /rule-sets |
Staff | farm.reconciliation_rules.manage |
| Read a rule set | GET /rule-sets/{rule_set_id} |
Organization users, staff or clients | none: any member of the Organization |
| List a rule set's reliability rankings | GET /rule-sets/{rule_set_id}/reliability |
Organization users, staff or clients | none: any member of the Organization |
| Add a reliability ranking | POST /rule-sets/{rule_set_id}/reliability |
Staff | farm.reconciliation_rules.manage |
| Re-run resolution | POST /resolution-runs |
Staff | farm.reconciliation_rules.manage |
5.5.2.7.3 Live Updates¶
A WebSocket at /reconciliation/v1/live follows the rules for live updates. New data issues are the alerts a farm acts on. The socket pushes data_issue.opened.v1 and data_issue.closed.v1 for the Organization while the issues screen is open; the screen loads the list through listDataIssues. The connection is authenticated with the same token as REST, closed when the screen is not visible, and reconnects with growing delays.
5.5.2.7.4 Contract v1¶
Proposed version
v1 is a proposal for review: its endpoints, errors and capabilities were designed from the requirements and the flows and are not confirmed. It leaves proposal with its first release; from then on it changes only as described in Every API Is Versioned.