Document api types wrt validation

Part 3 in a series of changes towards data validation.
Meta point, we should try to figure out how to integrate this w/ the .raml file so that they stay in sync.