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.