Revised API documentation for v1

@rodrigopavezi please review.

Please note that sample code references are still using "update", you will need to rename them after the sample code is revised.