hypothesis / hypothesis/product-backlog

Provide a public real-time API for subscribing to annotation updates

Open
#212 1 comment 0 reactions 0 assignees View on GitHub
API feature request h
Dominant language
No language data
Stars
122
Forks
7
PR merge metrics
No merged PRs in 30d

Description

## Feature Request Form
### Problem you are trying to address with this feature

Provide a way for third party developers to get real-time notifications when annotations are added to, updated or removed from a document. See [Slack discussion](https://hypothes-is.slack.com/archives/public/p1489217752364808) for the origins of this request.

The Hypothesis client uses the [Real Time API](https://h.readthedocs.io/en/latest/realtime/) for this, but the protocol for subscribing to annotation updates for a URL is a) not documented and b) not consistent with the APIs that are documented.

### Your solution

1. Design an API for a client to indicate the URLs that it is interested in receiving annotation updates for and receiving those updates. This API should be consistent with [the protocol used by the examples](https://h.readthedocs.io/en/latest/realtime/#server-messages).
2. Implement this API and modify the client to use it instead of the current undocumented API.
3. Document the API on [RTD](https://h.readthedocs.io/en/latest/realtime/#server-messages)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the Real Time API server-messages documentation and the protocol used by its examples, then trace how the Hypothesis client currently subscribes to annotation updates. Define a consistent public subscription protocol, update the client to use it, and document the completed API on RTD.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.