Open will-moore opened 5 months ago
For both of these URLs we'd want to filter by Annotation type
api/v0/tagannotations
For me the primary concern of using each annotation type in the path is the potential explosion of endpoints both at the top-level as well as each object level.
Personally, I find a type
query parameters and possibly a namespace
for the annotation endpoints gives all the required flexibility.
Also api/v0/annotations/
/tagannotations/ etc for listing Tags etc?
I think this depends on the decision made above. If we have api/v0/annotations?type=<type>
at the top-level, I would use the same pattern for api/v0/annotations/<id>/annotations/?type=<type>
api/v0/objects/?annotation=id to list the parent objects (projects, datasets etc) linked to child annotation:id.
An alternative suggestion would be to have N api/v0/annotations/<id>/<objects>
endpoints. A constraint is that it forces us to enumerate the annotatable objects (projects
, datasets
, images
,rois
...) exposed via this API. Additionally, this creates no single API endpoint to list all objects linked to an annotation.
On the plus side, this follows the pattern currently used for parent/child relationship like project/dataset using api/v0/datasets/<id>/projects
. I am also concerned about exposing an api/v0/objects
top-level endpoint knowing that all objects are currently not necessarily marshalled.
api/v0/annotations/?dataset=123 for listing child Annotations linked to parent Dataset? We do support api/v0/images/?dataset=123 for listing child Images of a Dataset, so it's consistent with that, but in the case of api/v0/annotations/?annotation=123 we are listing parent annotations, not children, so this might be confusing?!
I had missed this variant using the query parameter. Reading https://omero.readthedocs.io/en/stable/developers/json-api.html#list-images, the response of api/v0/m/images/?dataset=<id>
is expected to be equivalent to api/v0/m/datasets/<id>/images/
. Is there a reason to support both forms?
A few additional comments:
offset, limit, owner, group, normalize
should be supported?
See https://github.com/ome/omero-marshal/pull/78#issuecomment-1932882962 and discussion below that.
Endpoints we'd want to support:
api/v0/annotations
for listing all annotationsapi/v0/m/objects/<id>/annotations
for listing child Annotations linked to various objects (projects
,datasets
etc).api/v0/tagannotations
,api/v0/fileannotations
etc. which matches omero object namesapi/v0/annotations?type=file
. which is what's used inwebclient/api/annotations
and could allow multiple types e.g.?type=file&type=tag
(although we don't support this in webclient)./annotations
URLs we'd want?ns=my_namespace
.api/v0/annotations/<id>/annotations/
to list the child annotations linked to parent annotation:id. Alsoapi/v0/annotations/<id>/tagannotations/
etc for listing Tags etc?api/v0/annotations/?annotation=id
to list the parent annotations linked to child annotation:id. Alsoapi/v0/tagannotations/?annotation=id
etc for listing Tags etc.api/v0/objects/?annotation=id
to list the parent objects (projects
,datasets
etc) linked to child annotation:id.Question: do we want to support:
api/v0/annotations/?dataset=123
for listing child Annotations linked to parent Dataset? We do supportapi/v0/images/?dataset=123
for listing child Images of a Dataset, so it's consistent with that, but in the case ofapi/v0/annotations/?annotation=123
we are listing parent annotations, not children, so this might be confusing?!cc @chris-allan @sbesson @joshmoore