doc/api.md could be made clearer

[maximilien]

While trying to add metering (Abacus) support for the CF samples go_service_broker I found it a bit hard, or maybe not as clear as it could be, what APIs are provided by Abacus vs the ones that I (as a service broker writer) should implement and be called by Abacus. I would be nice to have the api.md be separated or at least demarcated in terms of responsibilities.

Also, a simple diagram or maybe a couple of sequence diagrams could be very useful. See this diagram about how the CC calls a service broker for async operations as an example.

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this. You can view the current status of your issue at: https://www.pivotaltracker.com/story/show/105262100.