API improvements

[cskwrd]

I have written a swagger spec for the API, here. It should cover the API that is in production currently, however, some of the types for the model classes are potentially incorrect as it isn't quickly apparent from the flask API what the types should be.

Could you please use it to generate the API using swagger?

Doing so has a couple of benefits:

• The API docs become the scaffolding of the API itself. Essentially, updating the docs (a.k.a. swagger spec) updates the API.

• Using swagger UI, the API docs are accessible to all in an almost completely language agnostic format (see Swagger Petstore example).

• By providing a swagger spec file, clients (including model classes) for consuming the API can also be generated. This would make updating the distributed client already written a breeze to change when API changes occur.

I know that this should probably be a PR, but I don't have any experience with python.