API: Return list of containers having updates available (or most recently updated)

[travipross]

Is your feature request related to a problem? Please describe.
I am looking to query watchtower via another service (for example: Home Assistant RESTful API integration) and be returned a list of containers which have updates pending.

Describe the solution you'd like
I would like to be able to call some URL (similar to the /v1/update path) and be returned a JSON array of containers which have updates available. As a bonus, it would be nice to see a selection of other stats in the payload, such as "image", "container_name", "last_scanned", or "last_updated".

One solution may be to define a response payload for the /v1/update route, which includes names of containers updated (or in the case of --monitor-only, have updates available).

Another solution would be to create a brand new endpoint which is solely used for the purpose of getting the latest scan results. (/v1/status?).

Describe alternatives you've considered

1. I have enabled --monitor-only in combination with --http-api-update. When making a request to /v1/update, the API witholds a response until all containers have been scanned/pulled, and I see in the watchtower logs that several updates are available. The --monitor-only argument is respected, and containers are simply scanned, not updated. However, an empty 200 response is returned to the client which called the /v1/update action. Given that the call hangs until all scans are complete, it should be possible for the results of that scan to be returned as part of the HTTP response.
2. I have tried to implement a solution using the metrics API (calling /v1/metrics when the --http-api-metrics was passed). I'm able to see the metrics, but as I understand, Prometheus doesn't support arbitrary string-type metrics, which means there is no way to make a Prometheus-compatible solution using that endpoint. At best, one could poll for the number of containers having updates, but this aggregate information is less useful than a contextual list of which containers have updates available, rather than how many containers.

Additional context
Home Assistant RESTful integration is just one example of a client that could benefit from such a feature. In the absence of generic HTTP webhook-style notifications, opening up this information via a poll-able endpoint would expand the ability for users and developers to integrate with watchtower. Returning a list of containers from an endpoint allows other applications to give additional useful context that is clearly already available.

[github-actions]

Hi there! 👋🏼 As you're new to this repo, we'd like to suggest that you read our code of conduct as well as our contribution guidelines. Thanks a bunch for opening your first issue! 🙏

[piksel]

I did a PoC for "notification stats" which created the structure for such an enpoint (/v1/status). It could simply return the Report generated for the most recent session, but perhaps with some additional meta, such as when it was run, what triggered it, filters applied etc.
The same response could be returned for /v1/update as well if, as you say, the server doesn't respond until the full run has been completed.

[travipross]

Ah that's great. That looks like exactly the sort of information I'm looking to see through the API. I'd love to see that incorporated.

[piksel]

Blocked by #981

[piksel]

This is the current output of a WIP implementation:

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[cdstg]

This looks good any progress ?

[piksel]

The WIP was closed due to lack of interest: #1000

[simskij]

The WIP was closed due to lack of interest: #1000

And now the issue suffers the same faith.