[API-Design] - Input validation

Right now we have no validation over our public API points meaning that we are currently forced to deal with inputs that we don't expect.

Closes #862
hmm might be nicer to throw an exception or error in that case.