Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Make API simpler: Can all reports be a processed report? #7070

Open
tsteur opened this issue Jan 25, 2015 · 5 comments
Open

Make API simpler: Can all reports be a processed report? #7070

tsteur opened this issue Jan 25, 2015 · 5 comments
Labels
c: Platform For Matomo platform changes that aren't impacting any of our APIs but improve the core itself. Task Indicates an issue is neither a feature nor a bug and it's purely a "technical" change.
Milestone
Backlog (Help wan...

Comments

@tsteur
Copy link
Member

tsteur commented Jan 25, 2015

This would be a change for Piwik 3.0 as it breaks API.

Currently we do have normal report API calls such as &method=UserCountry.getCountry link and the same as a processed report which would be &method=API.getProcessedReport&apiModule=UserCountry&apiAction=getCountry link.

I'm not 100% sure about the difference of those two reports but I think it is basically mainly this:

  • ProcessedReport contains a lot of metadata around the actual report data such as report name, columns.
  • ProcessedReport seems to contain less columns eg the actual report might contain goals etc. (ProcessedReport contains only columns that should be displayed in the UI whereas the actual report output contains all columns?)

The question is do we need those two different kind of API outputs? We can at least use this issue to clarify the differences between those reports and why we need them. Probably we do need both types but I only wanted to start this discussion in case we can simplify things here. Eg we could add a URL param metadata=0 which hides all the metadata and it would be similar as before. Another URL param could be only_to_be_displayed_columns=0 (name to be defined). Or to stay backwards compatible processed=1 would add metadata and only return displayed columns.

@mattab
The change in terms of API output would be very big and would break many clients/consumers. Therefore the change might be not even worth it even though we could break the API with Piwik 3.0
@tsteur tsteur added the c: Platform For Matomo platform changes that aren't impacting any of our APIs but improve the core itself. label Jan 25, 2015
@tsteur tsteur added this to the Piwik 3.0.0 milestone Jan 25, 2015
@mattab
Copy link
Member

mattab commented Feb 10, 2015

Correct, Metadata adds metadata as well as selects a subset of columns so that the report can be directly displayed in the client without worrying to filter columns. metadata is documented in this guide

I don't think we could break API for all users in this way. However maybe we could add a new parameter &metadata=1 that would transform the API report and make it the Metadata report for this report. Then it would stay BC and we could simplify the Doc for the metadata API by telling user to append &metadata=1 to standard export API URLs. It would be like a shortcut to get metadata report which would make lots of sense... thoughts?

@tsteur
Copy link
Member Author

tsteur commented Feb 10, 2015

I think processed=1 makes sense since we already have params like documentation=0/1 etc. and we would stay BC. API.getProcessedReport can be removed/deprecated then. metadata=1 doesn't make as much sense since the added metadata is not the only difference it causes. This issue is not really so important to me but would be nice if we could make things a bit simpler. We could also just leave it like it is but consider it for the new REST API

@mattab
Copy link
Member

mattab commented Feb 10, 2015

To stay BC API users would have to add processed=1 so it's risky as many may not be able to. Or we could, on upgrade from < 3.0.0 to >= 3.0.0 we could add a config hack upgraded_pre3_API_set_processed=1 if you see what I mean...

@tsteur
Copy link
Member Author

tsteur commented Feb 10, 2015

API users wouldn't have to do anything. It would be automatically BC. As processed=0 would be default, optionally they can pass processed=1 to get a processed report.

@mattab
Copy link
Member

mattab commented Feb 10, 2015

👍

@mattab mattab added the Task Indicates an issue is neither a feature nor a bug and it's purely a "technical" change. label Feb 19, 2015
@mattab mattab modified the milestones: Mid term, 3.0.0 Aug 13, 2015
@mattab mattab modified the milestones: Long term, Mid term Dec 5, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
c: Platform For Matomo platform changes that aren't impacting any of our APIs but improve the core itself. Task Indicates an issue is neither a feature nor a bug and it's purely a "technical" change.
Projects
None yet
Milestone
Backlog (Help wanted)
Development

No branches or pull requests
2 participants
@tsteur @mattab