You're right. We could have done a better job at documenting the REST API. We've been slowly introducing and fixing issues with the the REST API since it's debut. We never fully announced it as it was still very much a work in progress. However in WC 2.3 I'm happy to announce we've significantly improved the REST API and documentation.

Without a doubt we're also going to have many more resources joining Automattic and their talented group.