Defining the API

[CrazyPython]

Let's concretely define the API in the wiki. It'll help us think straight and give us a better idea of where we're headed.

This isn't the floaty kind of issue that I usually create. I really think this will help us out.