Getting realtime events

[Jan Wielemaker]

Hi,

I'm totally new to Hypothesis.  Seems like a promising project!  I'm involved in a project where we will try to allow people making formal statements about a document, reason about the consequences of these annotations and report feedback to locations in the document that confirm or deny these consequences.   The overall design idea is to let people make annotations and have a bot watching these and create annotations in reply.

I got most of the basics working: reading annotations and making annotations, but I have some trouble with the realtime interface.  I can connect to the websocket, send a whoami and get the right reply.   I don't seem to get any information on new/edited/etc annotations of the same user though.  The docs for _events_ say

> if an annotation is made which matches one of the client’s subscriptions, the client will receive an event message

What does this mean?   The docs say nothing about how to subscribe.

       Thanks --- Jan

P.s. Generated the client API from the OpenAPI description, but had to fix a number of bugs and omissions.  Should I discuss there here or make a PR?

[Jan Wielemaker]

On Monday, May 18, 2020 at 9:55:58 PM UTC+2, Jan Wielemaker wrote:

 I can connect to the websocket, send a whoami and get the right reply.   I don't seem to get any information on new/edited/etc annotations of the same user though.  The docs for _events_ say

> if an annotation is made which matches one of the client’s subscriptions, the client will receive an event message

What does this mean?   The docs say nothing about how to subscribe.

Some watching of the Chrome client and poking around in the source of `h` (filter.py) later I found one needs to set a filter.  For example:

 {"filter": {"match_policy":"include_any", "clauses":[ {"field":"/uri", "operator":"one_of", "value":[ <URI> ], "case_sensitive":false} ], "actions":{"create":true,"update":true,"delete":true} } }

[Robert Knight]

Hi Jan,

The Hypothesis real-time API is used by the client but is not currently documented as a public API. We had planned to rework it with a better interface before doing so. That said, we don't plan to make significant changes in the near future as we have other priorities. Although the filter syntax is very flexible, the API only really supports three things: Asking for updates to annotations that match a specific URL, asking for updates to annotations that have a specific ID or asking for updates to annotations that are part of a particular conversation thread. You can find examples of these in the tests at https://github.com/hypothesis/h/blob/master/tests/h/streamer/filter_test.py. If you search the client codebase for references to `streamFilter` you can find out what filters it uses: https://github.com/hypothesis/client/search?q=streamFilter&unscoped_q=streamFilter

Kind Regards,

Rob.

--
You received this message because you are subscribed to the Google Groups "dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dev+uns...@list.hypothes.is.
To view this discussion on the web visit https://groups.google.com/a/list.hypothes.is/d/msgid/dev/85b2b5d5-d7f3-4bc7-a898-8185816b0618%40list.hypothes.is.

--

Kind Regards,

Rob

[Jan Wielemaker]

Thanks Rob,

Appreciated.  I actually want to watch activity in a group.   A filter on `/group' set to the group id seems to work fine.   I now have a demonstrator bot that can watch a group in realtime and add replies or new annotations.   There are some wishes, but I think this is good enough to evaluate whether the project as a whole wants to use Hypothesis as a component or not.   If so, there will likely be more questions :)

I do have some patches for `hypothesis-v1.yaml` and related files.  Make a PR?