The use case that brough up this issue is DEER. DEER often has to expand entities by gathering the relevant Annotations targeting the entity and assembling an expanded objects from those Annotation body properties. This happens on the client and requires many /query requests for relevant data, which is taxing on RERUM and time consuming for DEER. Almost every application building entities in RERUM has to do something similar.
As such, RERUM should accommodate a more generic endpoint to do the expansion work.
- GET /v1/id/:_id/expanded - May contain basic options that can be passed in (such as generator) but is really imagined as that plain GET where nothing else is supplied. By default, this would gather all the latest leaf Annotations for the entity with id '/v1/id/:_id'. The entity itself has a generator, but nothing says we only want Annotations created by that generator so it will not be used as a filter without something directing it to do that. GET means it'll be cached well and quick with only a few flags.
- POST /v1/id/:_id/expanded - Will contain a JSON body. That JSON body provides parameters for the expand job. It is not expected that this will work with browser cache the same as the GET. POST means I am trying to set an expectation and reduce back and forth.
Clients may need to know which Annotations were picked. That means properties built from Annotations onto the entity may need to record the id(s) of the Annotation(s) they came from in some way. This is particularly important for citationSource in DEER. We will have to think about this, perhaps it is not necessary.
Clients that use this endpoint can expect entities that air on the raw side. Expansion will put properties onto the entities that match that raw data from the Annotation body as nearly as possible. If the client application needs the data in a certain shape then it is up to the client application to take the response and format it for its internal needs.
The endpoint itself should be designed to initiate the best MongoDB data look up pipeline to achieve this. For example, it may be best to do this as an aggregation. We want to research this, as we are not sure what the best way to do this would be yet.
The use case that brough up this issue is DEER. DEER often has to expand entities by gathering the relevant Annotations targeting the entity and assembling an expanded objects from those Annotation body properties. This happens on the client and requires many /query requests for relevant data, which is taxing on RERUM and time consuming for DEER. Almost every application building entities in RERUM has to do something similar.
As such, RERUM should accommodate a more generic endpoint to do the expansion work.
Clients that use this endpoint can expect entities that air on the raw side. Expansion will put properties onto the entities that match that raw data from the Annotation body as nearly as possible. If the client application needs the data in a certain shape then it is up to the client application to take the response and format it for its internal needs.
The endpoint itself should be designed to initiate the best MongoDB data look up pipeline to achieve this. For example, it may be best to do this as an aggregation. We want to research this, as we are not sure what the best way to do this would be yet.