5.5.2.4 Animals
The Animals domain of farm. The animal registry: animals with their identifiers, breed and profile evidence, groups and memberships, ownership and transfers, and the catalogs of species and breeds. Organization users work on the animals their Organization owns or manages; staff maintain the catalogs and the bull catalog. It is one API, with its own contract and its own version.
5.5.2.4.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://farm.moonitoring.com/animals/v1 |
animals/v1/openapi.yaml |
The resources follow the data model. Data typed in the app enters as a raw file of the Organization's MoonitoringAppChannel feed, so AnimalRegistration and AnimalProfileEvidenceInput are parsed like any source. AnimalView joins an animal with its identifiers, breeds, ownership and groups for one screen.
5.5.2.4.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 an Organization's animals | GET /organizations/{organization_id}/animals |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| Register an animal | POST /organizations/{organization_id}/animals |
Organization users, staff or clients | farm.animals.update or farm.reference_data.manage |
| Read an animal | GET /animals/{animal_id} |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| List an animal's profile evidence | GET /animals/{animal_id}/profile-evidence |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| State profile attributes | POST /animals/{animal_id}/profile-evidence |
Organization users | farm.animals.update |
| List an animal's breed composition | GET /animals/{animal_id}/breeds |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| Read an animal's registry history | GET /animals/{animal_id}/history |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| List an animal's identifiers | GET /animals/{animal_id}/identifiers |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| Attach an identifier | POST /animals/{animal_id}/identifiers |
Organization users, staff or clients | farm.animals.update or farm.reference_data.manage |
| Invalidate an identifier | POST /identifiers/{identifier_id}/invalidate |
Organization users, staff or clients | farm.animals.update or farm.reference_data.manage |
| List an animal's ownership periods | GET /animals/{animal_id}/ownerships |
Organization users, staff or clients | farm.animals.read or farm.canonical_data.read_all |
| Transfer an animal | POST /animals/{animal_id}/transfers |
Organization users | farm.ownerships.transfer |
| Transfer a group | POST /animal-groups/{group_id}/transfers |
Organization users | farm.ownerships.transfer |
| List an Organization's groups | GET /organizations/{organization_id}/animal-groups |
Organization users, staff or clients | farm.animal_groups.read or farm.canonical_data.read_all |
| Create a group | POST /organizations/{organization_id}/animal-groups |
Organization users | farm.animal_groups.manage |
| Read a group | GET /animal-groups/{group_id} |
Organization users, staff or clients | farm.animal_groups.read or farm.canonical_data.read_all |
| Update a group | PATCH /animal-groups/{group_id} |
Organization users | farm.animal_groups.manage |
| Archive a group | POST /animal-groups/{group_id}/archive |
Organization users | farm.animal_groups.manage |
| List a group's members | GET /animal-groups/{group_id}/members |
Organization users, staff or clients | farm.animal_groups.read or farm.canonical_data.read_all |
| Add an animal to a group | POST /animal-groups/{group_id}/members |
Organization users | farm.animal_groups.manage_members |
| Remove an animal from a group | POST /group-memberships/{membership_id}/close |
Organization users | farm.animal_groups.manage_members |
| List species | GET /animal-types |
Organization users, staff or clients | none: any member of the Organization |
| Create a species | POST /animal-types |
Staff | farm.reference_data.manage |
| List breeds | GET /breed-types |
Organization users, staff or clients | none: any member of the Organization |
| Create a breed | POST /breed-types |
Staff | farm.reference_data.manage |
5.5.2.4.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.