Api prototyping

Last week @Logic-gate pushed an initial API design into documentation. This led to a flurry of prototyping with swagger.

Currently, in order to better visualize and discuss the developmet of the api, we've put a 'mock' server up at.

If you have suggestions please fork and PR!