Improve behavior of imgData endpoint for missing/broken images

[knabar]

This is a proposal to improve the behavior of the imgData endpoint in addition to the improvements in #584 / #653

For images with missing pyramid, missing files, etc. an exception is thrown internally and returned instead of the expected JSON response, but still in valid JSON. Each client currently needs to look out for that and handle it accordingly.

The main issue is that image metadata that should otherwise be still available is not passed along.

The proposal is to change this API or create a replacement that always returns available image metadata (dimensions, channels, etc.) and also includes any exceptions or errors in a predictable location in the JSON. Right now it is also not possible to distinguish between pyramids currently being generated but not available yet and pyramids that are permanently missing.

Since this will change the behavior significantly, perhaps a new endpoint should be created and imgData deprecated?

Additionally, it would be helpful to make certain server configuration settings available to clients, either with this endpoint (if sensible and related) or via an additional new endpoint. For example, iviewer currently makes node descriptions available to the client via Django templating; if we had an API not every client would have to reimplement this.

cc: @jburel @will-moore @sbesson

[will-moore]

As an example of this issue, see https://idr.openmicroscopy.org/webclient/imgData/1230742/

It should be possible to add the missing metadata to that without breaking any client that is looking for the Exception?
I would prefer not to add a new image JSON endpoint.

Alternatively, is it practical to consider adding info to /api/v0/m/images/ID/ (e.g. https://idr.openmicroscopy.org/api/v0/m/images/15190883/ ) instead of creating a new endpoint?

This already has Pixels, Channels (name but not rendering info).

[chris-allan]

Making the handling of ConcurrencyException similar to that of Exception where the full normal payload is preserved and the exception details additive would be a potential alternative. A separate code path could then be added specifically for MissingPyramidException which might add a missingPyramid or other keys to the existing meta block.

If we can look at the exception handlers in omero-iviewer, omero-figure and the classic omero-web viewer that should give us a sense of how viable such a proposal would be.

[sbesson]

Conceptually, I am in favor of using more the OMERO.web JSON API endpoints whenever possible. However, in that case, I am not sure it helps us. An important component of the imgData response for whole slide images is that it exposes some of the internal details of the image such as the tile size or the resolution levels. These concepts are completely outside the OMERO model and thus do no map into any of the current marshalled objects.

Together with #653, we have 2 issues that might drive the extension of the imgData response in a backwards-compatible way. As shown by the discussion above, it is not fully clear what the current contract is for some of these edge cases. I propose we can also use this as an opportunity to review https://omero.readthedocs.io/en/stable/developers/Web/WebGateway.html#imgdata and

1. document the current expectations including the possible exceptions and how they should be handled via the clients
2. document the new behaviours introduced in the next minor release of OMERO.web

[chris-allan]

Can confirm that the following diff does not affect the functionality of the classic OMERO.web viewer or omero-iviewer:

diff --git a/omeroweb/webgateway/marshal.py b/omeroweb/webgateway/marshal.py
index 712246bf2..f80de0bc0 100644
--- a/omeroweb/webgateway/marshal.py
+++ b/omeroweb/webgateway/marshal.py
@@ -172,7 +172,7 @@ def imageMarshal(image, key=None, request=None):
             return rv
     except omero.ConcurrencyException as ce:
         backOff = ce.backOff
-        rv = {"ConcurrencyException": {"backOff": backOff}}
+        rv["ConcurrencyException"] = {"backOff": backOff}
         return rv
     except Exception as ex:  # Handle everything else.
         rv["Exception"] = ex.message

Definitely allows applications that would like to use the metadata that comes from this endpoint even when a pyramid is being generated.

[knabar]

Can confirm that the following diff does not affect the functionality of the classic OMERO.web viewer or omero-iviewer:

Definitely allows applications that would like to use the metadata that comes from this endpoint even when a pyramid is being generated.

This change would also be my suggestion at this time, with possible a small addition that would allow clients to just check for Exception instead of both Exception and ConcurrencyException:

     except omero.ConcurrencyException as ce:
         backOff = ce.backOff
-        rv = {"ConcurrencyException": {"backOff": backOff}}
+        rv["ConcurrencyException"] = {"backOff": backOff}
+        rv["Exception"] = ex.message
         return rv

Here are the currently possible responses of the call:

Possible response codes:

• 200
• 403 if not logged in
• 404 if image not found

Response on ConcurrencyException:

{"ConcurrencyException": {"backOff": backOff}}

Response on other exceptions:

{
    “id”: number,
    “meta”: {...},
    “perms”: {...},
    “Exception”: “exception message”
}

On success:

{
    “id”: number,
    “meta”: {...},
    “perms”: {...},
    “tiles”: false,
}

{
    “id”: number,
    “meta”: {...},
    “perms”: {...},
    “tiles”: true,
    “tile_size”: {...},
    “levels”: number,
    “zoomLevelScaling”: {...}
}