Provide a Reporting API guide

[tsteur]

So far we have 3 reports related to the Reporting API:

• API-Reference: Reporting API Reference
• Integrate: Reporting API Tutorial
• Integrate: Querying the Reporting API
• Piwik In Depth: Reporting HTTP API

None of those guides explains on one page what the Reporting API is, what it can be used for, and how to query it step by step. I'm currently writing a blog post about "How to expose new methods in the Reporting API" but noticed I can actually not link to any of those pages for people who don't know much about it. The In Depth Guide seems to be the only one who explains in a sentence what it is but then it follows be unrelated DataTable Filters etc. The Querying the Reporting API contains only 2 bigger examples but not much explanations etc. Also the second part of this guide should be rather in a separate guide and we need to discuss whether it is actually a good idea to recommend to load index.php to do that. I will create a separate issue on piwik/piwik for this. The Tutorial is a good start but doesn't explain what it is, what it can be used for, doesn't mention authentication etc.

The API-Reference is purely a list of parameters and methods but doesn't explain anything (which is good).

Maybe we can write a single page that explains what it is, what it can be used for, and how to make a successful call with authentication if needed and maybe explain a few more basics like period and date. Then we can link to the API-Reference. We could also write a small section about Segmentation and Metadata API and link to their pages on developer.piwik.org. A while ago I wrote an article for a German PHP Magazine maybe we could reuse some parts or the structure of it in some way.