For which use cases do we use AnimalEvents and for which do we just use PUT/POST/DELETE?

[thomasd-gea]

We were discussing animal status and how these could be changed through a StatusChangeEvent. Now I'm wondering: should we also accept a put/post to the animal endpoint to add new animals to the farm or change some details of an animal?

Example: I have a typo in the name of an animal (or even in the eartag). Do I have to send a "ChangeAnimalDataEvent" or even an "ChangeAnimalNameEvent"? Or do I just "PUT" the animal with the fields I'd like to change, but I have to send all the fields that I don't want to change as well?

However, for animalSets we said that an event to add/remove animals would be a good approach. How is this different than just PUTing a new list entity with the references and why should I avoid (or allow) it?

The general point behind this is for me: what do we support as an event and what not? How is this fine line defined? Some systems might want to have events to track whenever basic animal data was changed (and exchange that through the ICAR interface), but some would just not care and accept every post/put that is sent. Some would only allow adding animals to the system via events, some would just accept that animals are added/removed through PUT or DELETE.

Do you have some ideas/opinions on this?

In addition to this I think there are expectations that when an animal action is executed (e.g. set dry), that this might have a side effect of e.g. a changed animal status. But what about the other way around? If I just change the status of an animal via a PUT request, does this imply that internally a "ChangeAnimalStatusEvent" is created automatically? But maybe this is something that the communicating systems have to agree upon.

[alamers]

In my experience, an event is an after-the-fact message to inform that a change has happened. PUT/POST/DELETE's are commands, instructing the other party to do something (which may fail).

So how does that translate to ICAR? I would not use events to change state, just to inform about a change already happened. For changing a resource, the other verbs exist. Note that there are some semantics defined already by Fielding/REST standards:

• PUT: make a change to the URI specified. note that PUT must be idempotent so it can be used for updates, typically not for create
• POST: make a non-idempotent change to the URI specified. This is typically used for creates. Most commonly, id creation is handled by the server, so a POST to /animals will create a new subresource (the animal) below /animals as /animals/{id}.
• PATCH: make a non-idempotent local change to the URI specified. This would be used to only patch a few specific fields of a resource. Since it doesn't require idempotency, I've also seen it used for small more command-like instructions that do not target a specific field but rather some process.

So, to set an animal dry, I'd expect something like this:

• a client PATCHes the /animal/{id} with {dry-state: false} as a body (if we have a specific field for that), or a client PATCHes the /animal/{id}/dry-state with some additional details in the body.
• the server process this and it may generate some events based on all the processes that it supports. Typically, this would at least be an AnimalStateChangedEvent or similar, but maybe it also triggers other health, milk or reproduction events.

[cookeac]

The vast majority of animal attributes should be able to be updated through a PUT or PATCH.

While animals COULD in theory be created with a POST (and events certainly should be), creating an animal with a POST might leave the server wondering how the animal got there - was it an existing animal being imported into the server, a new animal received from another farm, an animal just being registered for the first time? For MOST servers, this matters, so they would not normally allow a POST to create animals. SOME servers may not care, particularly if they are just synchronising data and not making other judgements, in which case they may allow POST to create animals.

Now to reproductive and lactation status:
When first proposed, these attributes were to be computed by services that understood how to analyse the series of events that have occurred for the animal, and correctly derive the status. The primary source of information was to be the animal events (for instance, Drying Off, Mating, or Pregnancy Check).

During the development of these attributes, we noted that particularly with reproduction, it might be possible to observe that an animal was no longer pregnant, but not know why (was it incorrectly recorded initially, aborted, had dead progeny, had live progeny that could not be matched to the dam, etc). This could be represented by a "Not Pregnant" observation, OR an event to change the reproductive status, OR by simply PATCHing the animal to change its state.

In my opinion, it makes sense to support an event that tells us what the farmer observed. This will allow systems that do their own analysis of reproductive events to draw a conclusion, rather than leaving them with missing data. This is important, as they may use these events to derive other information for the animals or the herd (e.g. in-calf rates).
However, I would not make that argument about most other animal attributes.

[alamers]

I think I agree :). It is mostly a matter of semantics and while risking being pedantic, I'll dig a bit more to figure out when to use what:

Just to get to a proper definition for future changes: the event here is that a farmer did an observation, the originating 'system' (e.g. the farmer's app or management system) is thus probably a different system than the one keeping track of the animal state. This second system can thus freely decide to ignore the observation or to update the internal state.

[cookeac]

Rolling into issue #147