Repository navigation
Hypothesis API
The hypothesis API is ostensibly documented here:
https://h.readthedocs.io/en/latest/api-reference/v1/
However, the documentation isn't enough to create our own implementation (e.g., many fields only have names, not descriptions of what purpose they serve). This part of the wiki is intended to document the API for our purposes --- what it is, what it does, how it works, etc..
Because we're presumably going to be a small project merging two larger projects (Amusewiki and Hypothesis), we can't just hack around as though these code bases are our own. We need to manage our design such that upstream commits can easily be merged, and our patch series rebased. Because of this, there will be instances where it would be nice to redesign how the API works to better suit us, but we should avoid doing so because changes in that sort of thing could lead to ugly patches down the road. In other words: it will pay off to keep a clean boundary between the two halves of the project, and the API as it exists is a good way to do that.
We are currently targeting v1 of the API. v2 (experimental) is basically the same as v1 right now, but we should keep an eye on its development so that we don't get blindsided when the upstream client switches over. That said, my expectation is that the Hypothesis devs will leave plenty of transition time. Even though I'm not aware of any alternative clients, they seem to take their role as vanguard of the web annotation standard seriously.
For now, we are only targeting portions of the API that are actually used by the client. This includes the MVP, as well as any foreseeable future release. You can find the code where these API calls are created in the client towards the end of the api.js file. We do, however, still document every portion of the API known to us, in case it proves useful for reasons other than creating our own implementation of it. Which portions we're planning on implementing, and when, should be primarily tracked through the issue tracker.