Thoughts on current API

I was asked to take my current thoughts about our API situation and write them up for discussion. Here's the heuristic feedback:

- Having the "Hypothesis API" and "Hypothesis Real Time API" separation is wrong to me. We should have one place for what API is and, under that, we can have a real-time area.
- Regarding the standard API ( I did not use the real-time API)
- Authorization using a long-lived developer token as the primary mechanism is bad and really puts our API in a position that makes it unusable for production apps. We really need to get the work finished for oAuth before we can even advertise the use of the API, imo.
- The Authentication section of the documentation is confusing as hell. With a mix of "third-party accounts" only stuff and no good line defining the two feature sets. And, while we are at it, the "third-party accounts" verbiage from an API user standpoint (or anyone outside of H) is confusing at best. Aren't I a third-party account? (I am not hypothesis or the actual user?)
- Documentation only shows the minimum information but does not give any context of what is required, what is optional, what values are expected. This wouldn't be quite as necessary if our API was a less convoluted and reflected a friendlier schema (as opposed to a reflection of our internal model requirements).
- API model mirrors our internal requirements for the schema backing the API. This exposes lots of needless complexity to the end user. And to make it worse, the current documentation doesn't explain how the pieces of the model work. As an example, a user should be able to say something like `{ public: true }` and we would make the new annotation public. Instead of having to set `{ group: '__world__', permissions: { read: [ 'group:__world__' ] } }` for an annotation to be public. Though, the documentation doesn't actually tell you how to do that.

All of those pieces combined makes our API borderline impossible to have a self-service use of our API by third-parties. With the long-lived developer token being the only way

Review the standard API, Real Time API, and Authentication documentation discussed in the issue. Clarify whether the work covers API organization, OAuth, authentication terminology, documentation completeness, or schema simplification, then define concrete scope and acceptance criteria before implementation.

Written by the indexing model from the issue text.