First, Google defined the object CloudHealthcareSource that includes a single property: name. This name can be used to build a URL to get the resource. This approach allows to easily reference different objects such as our Note schema or any (FHIR) schema that could be added in the future. Simplify storing the DB record ID is not possible and advised because: 1) ObjectId in MongoDB are not unique across multiple collections, 2) does not implement ID opacity (good practice for security).
This implementation is the most straightforward. However it requires the user of the API to read the doc to figure out what the value of annotationSource must be the name of a resource. This design also limit future extension and is more likely to introduce breaking change than the approach adopted by Google with
One assumption we make if annotationSource is a string and not a schema that we can extend in the future is that the source of an annotation must be accessible through the same API service instance as where the annotation objects are saved. However, there could be benefit to storing annotation to a data node instance that is different from the data node that includes the source information, for example for scalability and performance reason.
Proposal
Defining CloudHealthcareSource.yaml limit the risk of introducing breaking changes in the future and provide more flexibility. Thus, I would recommend adopting this design.
The current design is based on the format adopted by Google Healthcare API.
First, Google defined the object
CloudHealthcareSource
that includes a single property:name
. This name can be used to build a URL to get the resource. This approach allows to easily reference different objects such as our Note schema or any (FHIR) schema that could be added in the future. Simplify storing the DB record ID is not possible and advised because: 1) ObjectId in MongoDB are not unique across multiple collections, 2) does not implement ID opacity (good practice for security).We could have:
This implementation is the most straightforward. However it requires the user of the API to read the doc to figure out what the value of
annotationSource
must be the name of a resource. This design also limit future extension and is more likely to introduce breaking change than the approach adopted by Google withwhere
CloudHealthcareSource.yaml
would beOne assumption we make if
annotationSource
is a string and not a schema that we can extend in the future is that the source of an annotation must be accessible through the same API service instance as where the annotation objects are saved. However, there could be benefit to storing annotation to a data node instance that is different from the data node that includes the source information, for example for scalability and performance reason.Proposal
Defining
CloudHealthcareSource.yaml
limit the risk of introducing breaking changes in the future and provide more flexibility. Thus, I would recommend adopting this design.