fixes #337 - add and document api ordering