updates API docs and diagram

$subject

please have a look at the descriptions and attributes - obviously this is still fluid and will change again but does this match what you currently know?