JSON API support for Annotations

[will-moore]

See ome/omero-marshal#78 (comment)
and discussion below that.

Endpoints we'd want to support:

• api/v0/annotations for listing all annotations
• api/v0/m/objects/<id>/annotations for listing child Annotations linked to various objects (projects, datasets etc).
  • For both of these URLs we'd want to filter by Annotation type. This could be done in 2 ways...
    • api/v0/tagannotations, api/v0/fileannotations etc. which matches omero object names
    • api/v0/annotations?type=file. which is what's used in webclient/api/annotations and could allow multiple types e.g. ?type=file&type=tag (although we don't support this in webclient).
  • Also for both of those /annotations URLs we'd want ?ns=my_namespace.
• api/v0/annotations/<id>/annotations/ to list the child annotations linked to parent annotation:id. Also api/v0/annotations/<id>/tagannotations/ etc for listing Tags etc?
• api/v0/annotations/?annotation=id to list the parent annotations linked to child annotation:id. Also api/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 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?!

cc @chris-allan @sbesson @joshmoore

[sbesson]

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:

• I assume for each endpoint, the standard query paramers offset, limit, owner, group, normalize should be supported?
• do we want to do anything in terms of annotation creation, update & deletion support as in https://omero.readthedocs.io/en/stable/developers/json-api.html#creating-and-saving-objects, possibly restricting it to sub-type of annotations initially?