API spec updates (editorial) based on Zhe Wu's review

This addresses #236.