RFC: API changes
This is a request for your comments about a change to the responses generated by GGCE API.
Why?
id
Objects are serialized as only their The current JSON serialization returns only the reference id
number instead of the full object when the same object had already been serialized. This means that client code needs additional processing before you can use deeply nested properties like taxonomySpecies.speciesName
.
Example of taxonomySpecies
serialized as only id
with current implementation:
[
{ "id": 1, "accessionNumber": "X1", "taxonomySpecies": { "id": 123, "speciesName": "something", "taxonomyGenus": { "id": 33 }, ... }, ... },
{ "id": 2, "accessionNumber": "X2", "taxonomySpecies": 123, ... }
]
requires processing so that "taxonomySpecies": 123
is converted to an existing object. The updated API will respond with fully serialized object:
[
{ "id": 1, "accessionNumber": "X1", "taxonomySpecies": { "id": 123, "speciesName": "something", ... }, ... },
{ "id": 2, "accessionNumber": "X2", "taxonomySpecies": { "id": 123, "speciesName": "something", ... }, ... },
]
Depth of serialization
API now uses a schema that is based on database entity classes, meaning that the responses include a lot of data in nested JSON that are not required for the function of the client. Deep nesting like accession.taxonomySpecies.taxonomyGenus.taxonomyFamily.name
requires a lot of data to be sent to the client:
[
{
"id": 1,
"accessionNumber": "X1",
"taxonomySpecies": {
"id": 123,
"taxonomyGenus": {
"id": 433,
"taxonomyFamily": {
"id" 55,
"taxonomyExtendedFamily": {
"id",
...
}
}
}
}
}
]
I propose that we change the schema and provide a more compact format of nested (referenced) records that provide the key information about the referenced entity and avoid using further nesting levels (taxonomy family, genus and species data is compacted into TaxonomyInfo
instead of using the full TaxonomySpecies
):
[
{
"id": 1,
"accessionNumber": "X1",
"taxonomySpecies": {
"id": 123,
"genusName": "Hordeum",
"speciesName": "vulgare",
"familyName": "...."
}
}
]
Benefits
- JSON complexity is reduced allowing for faster processing on the client and much smaller response size
- All objects will be fully serialized (even when repeated), reducing the processing required on the client
@jarias @1cgiar/palmira