Revamp APIv2 Docs

[kilrau]

We received feedback recently (e.g. via our TG group) that our APIv2 docs are not as comprehensive as our APIv1 docs in a way that the short swagger descsriptions are not enough to understand what a specific call does.

Also the he code examples might not be enough of a description for the typical order/flow is. Maybe we can combine APIv1-style descriptions linking to swagger for each call.

Specific things that are unclear:

• do I need an API key
• how do referrals work (Add separate Doc section for Referrals #12)