API v1 spec

This is still a work-in-progress, but any feedback is more than welcome.
One is a single entity while the other is a collection of those entities with some metadata. You should be able to write a simple parser per media-type. That would not be possible if you first had to check if the thing you're parsing is a list of things or just a thing.