Request movement- and reproduction-history of a single animal

[AndreasSchultzGEA]

Users of our interfaces of request for getting the history of a single animal at once instead of requesting several endpoint without proper filtering.
And - in our own business - we often have to request the history of single animals as well from national cattle-register to insert them in complete into our database, but some of them limit the data to be delivered by the dedicated endpoints in concerns of date/time probably for performance/payload reasons.
#492

[dirbSEGES]

Hi, my point of view is that it could be a solution to add a single animal as request parameter on all relevant message. like this ex.
/Locations/dk.herdnumber/25872/dk.animalnumber/2587210201/diagnoses
That is how we have solve this issue when a new animal is entering the herd.

Then you can request the history of a new animal entering the location.

If a new endpoint for history is made, we have to add all event messages into one new endpoint. This will be another kind approach of sharing data then the existing.

[AndreasSchultzGEA]

Thanks Ditlev for your comment.
If we provide interface which are not defined in the standard so far, we mostly design them the other way round:
/locations/dk.herdnumber/25872/diagnoses/dk.animalnumber/2587210201
This way, it is somehow an addition or a kind of filter for the well know standard-url

Nevertheless, a disadvantage is, that one has to request all endpoints to get the data of one single animal collected --> one request vs.

• 4*movement + 5-6*reproduction + x*health + y*diagnoses + ...

Really a lot of complexity! Each of this requests could fail, deliver a bad request, all of them have to be collected, etc.

[dirbSEGES]

If it will be an single endpoint where you can get all event of an animal, what is the reason to have all the other endpoints? Then this endpoint only can be use by single animal, right?

[cookeac]

We agreed that @AndreasSchultzGEA will propose a pull request that demonstrates filtering the existing API end points by animal identifier as @dirbSEGES proposed. This may be easier for people to implement serialisation and deserialisation of resources, even though it requires more calls. It may also allow collection of missing events of a single type for an animal.

[AndreasSchultzGEA]

I provided 2 slightly differing PR:
SEGES-style: #498
Filter-style: #499

[erwinspeybroeck]

I'm in favour of the filter style --> is conform with API design rules --> the endpoint in the example is pregancy -checks, and you want this for one animal, or you want a specifc period, or a modified-since, or only those with value true ....
The animal is just another filter.
We mostly add something like animals before the scheme and id, because you have to identify what you are filtering.

/location/pregnancy-checks/animals/scheme/id
to avoid misunderstanding with other filtering

[cookeac]

Discussed at Nov 27 meeting

• We prefer an API per event type rather than a potentially expanding multi-event API
• We prefer the filter method ?animal-scheme=x&animal-id=y

[cookeac]

Discussed at Nov 28 meeting

• We also prefer the filter method with query parameters
• If a server does not recognise these parameters (backwards compatibility) they will return the full set - no filtering
• If a server decides it will not support these parameters it can provide an HTTP error.

[AndreasSchultzGEA]

Good solution. I thought of it as well, but then I had to prepare a third PR.
Now, I have to ;-)

What about

• "?eu.animalId=DK2138349874984"
  instead of
• "?animal-scheme=x&animal-id=y"

The advantage is to have only one parameter (key-value) instead of two.

[damare]

As the scheme-id can literally be anything, it is not possible to define this in openAPI. Moreover, most frameworks do not allow dynamic query parameters for security reasons.

[cookeac]

Meeting 2025-01-23:
We decided that the preferred syntax should be: ?animal-scheme=x&animal-id=y

We could also support a URN convention - single string as: ?animal-identifier="URN:icar:animal:<scheme-name>:<animal-id>"

[AlexeyHardCode]

As specified in the task title, identifier fields were requested to be added to the Movement and Reproduction history events.

animal-scheme, animal-id and animal-identifier parameters have been added to the following methods:

1. Registration scheme:
   - GET arrivals
   - GET departures
2. Reproduction scheme:
   • GET pregnancy-checks
   • GET heats
   • GET inseminations
   • GET drying-offs
   • GET abortions
   • GET do-not-breeds
   • GET parturitions
   • GET mating-recommendations
   • GET gestations
   • GET repro-status-observations
   • GET repro-embyro-flushings (TYPO in the embryo word, which is corrected in PR)

Optionaly, identifier fields could be also added to:
Performance scheme:
- GET weights
- GET breeding-values
- GET conformation-scores
- GET type-classifications
Milk scheme:
- GET milking-visits
- GET test-days
- GET test-day-results
- GET daily-milking-averages
- GET milk-predictions
- GET lactations
- GET lactation-status-observations
- GET milking-withdrawals
Health scheme:
- GET diagnoses
- GET treatments
- GET treatment-programs
- GET health-status
- GET medicine-transaction (UPDATE identifier-scheme, identifier-id)
- GET attention-events (UPDATE identifier-scheme, identifier-id)
Feed scheme:
- GET feed-reports
- GET feed-recommendations

[AndreasSchultzGEA]

Agreed we on to include both alternatives or the URN-based - if possible?
I'm not sure any more.

[AlexeyHardCode]

@cookeac Do I understand it right, that we could have both options animal-scheme with animal-id and animal-identifier as URN
@AndreasSchultzGEA Does this seem excessive to you? Do you think we could incorporate these parameters into other methods in different schemes?

[cookeac]

@AlexeyHardCode @AndreasSchultzGEA we could have both approaches. My hesitation about this is that it would require all implementers to support both approaches. That is not hard, but is an extra thing to do.

The reason for using the URN approach is that it is a simple way to extend to a future, more standards-aligned approach. We did agree at the meeting we would do this, however.

I agree we would incorporate these into all the other GET collection methods - as it makes sense to be able to do this for other events as well. That does not have to be done in this PR - we could do this later.