matomo-org / matomo-org/developer-documentation

Provide a Reporting API guide

Open
#76 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Documentation
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.