Refactor API code to use annotator-store flaskless

Everything seems to work: reading, creating, updating, deleting, searching, permissions seem to work but need better testing, and in general more tests and thorough code review would be good.

To keep a consistent style and make refactoring easier, I decided to use traversal with a `@view_defaults` class everywhere, using the defaults class to specify the `context` predicate, so as to group the views within that. For the same reasons I do not use view names but use a resource for each location (I explictly state `name=''` for clarity, though that could be removed). I think this style works out nicely.

I put some questions in the comments, just search for the question marks.

The dependency on the next (flaskless) annotator-store version has yet to be added.
To me it's about expectations. If we state up front that we use python and
pyramid somewhere then we should expect developers to be familiar with them.

You would, I suspect, balk at a short summary of what classes and objects
are, or a lesson in python method resolution order, when opening a random
python file in a project.

We should absolutely document clearly that we use pyramid and that we
prefer traversal based routing but the place for that is definitely docs/

Let's put some effort into making our docs up to date next sprint and then
commit to keeping it that way.
On Jul 11, 2014 5:07 PM, "Gerben" <notifications@github.com> wrote:

> In h/api.py:
>
> > +"""
> > +A quick explanation for those unfamiliar with the Pyramid Web Framework.
> > +The resources defined in resources.py create the tree ('folder') structure using
> > +Pyramid's "traversal" pattern. For example, "/api/annotations/" will result in
> > +h.resources.AnnotationFactory being selected as the request's Context. For each
> > +group of Views, we specify (using @view_defaults) by which type of context these
> > +views can be triggered. That is, which class or interface the context should
> > +have.
> > +For a context (= resource = /some/path/) that implements different actions, we
> > +use @view_config to specify in which situation these views are to be triggered,
> > +for example to use a different view method on a GET than on a POST request.
> > +
> > +For more information about Traversal and View configuration, see (respectively):
> > +http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/traversal.html
> > +http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/viewconfig.html
> > +"""
>
>
>    1. It's partly about pyramid, partly about how we use pyramid
>    2. I think Pyramid can use a tl;dr summary and would love if more
>    projects would let me read their code without forcing me to first dive into
>    the frameworks they use.
>
> I'm fine with correcting or clearing up this documentation, or moving it
> into a readme or other source file, but I do really think we should have
> more documentation like this that explains our code in human-readable
> language.
>
> —
> Reply to this email directly or view it on GitHub
> <https://github.com/hypothesis/h/pull/1300/files#r14849759>.
>