5.5.2.6 Events
The Events domain of farm. What happened to an animal or a group, as each feed reported it (calvings, services, treatments, exits and the other canonical events), the periods derived from the resolved facts (lactations, dry periods, pregnancies, withdrawals), the catalogs of period and death kinds and each farm's configuration. Consumers who want one fact per real event read the Reconciliation API. It is one API, with its own contract and its own version.
5.5.2.6.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://farm.moonitoring.com/events/v1 |
events/v1/openapi.yaml |
The resources follow the data model. EventEntry carries the typed fields of every subtype behind one type, because an operator records one event at a time. farm.farm_configurations.manage is proposed: the catalog has no capability for req 43.
5.5.2.6.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 events | GET /organizations/{organization_id}/events |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| Record an event | POST /organizations/{organization_id}/events |
Organization users | farm.animal_events.record or farm.animal_diagnoses.record |
| Read an event | GET /events/{event_id} |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| List an event's revisions | GET /events/{event_id}/revisions |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| Read an event's lineage | GET /events/{event_id}/lineage |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| List the offspring of a parturition | GET /events/{event_id}/offspring |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| List the products of a treatment | GET /events/{event_id}/products |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| Correct an event | POST /events/{event_id}/correct |
Organization users | farm.animal_records.edit_own |
| Cancel an event | POST /events/{event_id}/cancel |
Organization users | farm.animal_records.edit_own |
| List periods | GET /organizations/{organization_id}/periods |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| Read a period | GET /periods/{period_id} |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| List period kinds | GET /period-types |
Organization users, staff or clients | none: any member of the Organization |
| Create a period kind | POST /period-types |
Staff | farm.reference_data.manage |
| List death kinds | GET /death-types |
Organization users, staff or clients | none: any member of the Organization |
| Create a death kind | POST /death-types |
Staff | farm.reference_data.manage |
| List a farm's configurations | GET /organizations/{organization_id}/configurations |
Organization users, staff or clients | farm.animal_records.read or farm.canonical_data.read_all |
| Add a farm configuration period | POST /organizations/{organization_id}/configurations |
Organization users | farm.farm_configurations.manage |
5.5.2.6.3 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.