matomo-org / matomo-org/developer-documentation
Provide a Reporting API guide
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 58
- Forks
- 88
- Avg merge
- 6d 3h
- Merged PRs (30d)
- 13
Description
So far we have 3 reports related to the Reporting API:
- [API-Reference: Reporting API Reference](http://developer.piwik.org/api-reference/reporting-api)
- [Integrate: Reporting API Tutorial](http://developer.piwik.org/guides/reporting-api-tutorial)
- [Integrate: Querying the Reporting API](http://developer.piwik.org/guides/querying-the-reporting-api)
- [Piwik In Depth: Reporting HTTP API](http://developer.piwik.org/guides/piwiks-reporting-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](http://developer.piwik.org/guides/piwiks-reporting-api) 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](http://developer.piwik.org/guides/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](http://developer.piwik.org/guides/reporting-api-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](https://translate.google.de/translate?sl=de&tl=en&js=y&prev=_t&hl=de&ie=UTF-8&u=http%3A%2F%2Fphpmagazin.de%2FDas-Piwik-REST-API-5859.html&edit-text=) for a German PHP Magazine maybe we could reuse some parts or the structure of it in some way.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the four linked Reporting API guides and the API Reference first, comparing their coverage of purpose, use cases, authentication, periods, dates, and query steps. Use the existing documentation structure as the entry point; done means one focused guide explains those basics clearly and links to the API Reference, Segmentation, and Metadata API pages without duplicating reference material.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100