some notes on the API

@brianloveswords I'm going to start developing the API against this 'spec'. Take a look at it and shoot feedbacks.