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.

Sign up for GitHub

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

Completing the API requests examples #20059

Open
Chardonneaur opened this issue Nov 28, 2022 · 2 comments
Open

Completing the API requests examples #20059

Chardonneaur opened this issue Nov 28, 2022 · 2 comments
Labels
c: Documentation For issues related to in-app product help messages, or to the Matomo knowledge base.
Milestone
For Prioritization

Comments

@Chardonneaur
Copy link

Hi,

On the API page within Matomo, there are many useful example requests, but for some reasons, many are missing whereas they are extremely useful, for example Annotations.add
@Chardonneaur Chardonneaur added the To Triage An issue awaiting triage by a Matomo core team member label Nov 28, 2022
@peterhashair peterhashair added c: Documentation For issues related to in-app product help messages, or to the Matomo knowledge base. and removed To Triage An issue awaiting triage by a Matomo core team member labels Nov 28, 2022
@peterhashair
Copy link
Contributor

@Chardonneaur thanks for reporting this, I guess we missing some of the documentation there.

@sgiehl
Copy link
Member

sgiehl commented Nov 30, 2022

@Chardonneaur All examples on the page that are currently displayed are kind of generated automatically, based on the parameter names.
This works without problems for most reporting methods. But for all API methods not working with the standard set of parameters, this doesn't work and would need some manually added examples or similar.
See

matomo/core/API/DocumentationGenerator.php

Lines 210 to 321 in 2fcd5e5

public function getExampleUrl($class, $methodName, $parametersToSet = array())
{
$knowExampleDefaultParametersValues = array(
'access' => 'view',
'userLogin' => 'test',
'passwordMd5ied' => 'passwordExample',
'email' => 'test@example.org',
'languageCode' => 'fr',
'url' => 'https://divezone.net/',
'pageUrl' => 'https://divezone.net/',
'apiModule' => 'UserCountry',
'apiAction' => 'getCountry',
'lastMinutes' => '30',
'abandonedCarts' => '0',
'segmentName' => 'pageTitle',
'ip' => '194.57.91.215',
'idSites' => '1,2',
'idAlert' => '1',
'seconds' => '3600',
// 'segmentName' => 'browserCode',
);
foreach ($parametersToSet as $name => $value) {
$knowExampleDefaultParametersValues[$name] = $value;
}
// no links for these method names
$doNotPrintExampleForTheseMethods = array(
//Sites
'deleteSite',
'addSite',
'updateSite',
'addSiteAliasUrls',
//Users
'deleteUser',
'addUser',
'updateUser',
'setUserAccess',
//Goals
'addGoal',
'updateGoal',
'deleteGoal',
//Marketplace
'deleteLicenseKey'
);
if (in_array($methodName, $doNotPrintExampleForTheseMethods)) {
return false;
}
// we try to give an URL example to call the API
$aParameters = Proxy::getInstance()->getParametersList($class, $methodName);
$aParameters['format'] = false;
$aParameters['hideIdSubDatable'] = false;
$aParameters['serialize'] = false;
$aParameters['language'] = false;
$aParameters['translateColumnNames'] = false;
$aParameters['label'] = false;
$aParameters['labelSeries'] = false;
$aParameters['flat'] = false;
$aParameters['include_aggregate_rows'] = false;
$aParameters['filter_offset'] = false;
$aParameters['filter_limit'] = false;
$aParameters['filter_sort_column'] = false;
$aParameters['filter_sort_order'] = false;
$aParameters['filter_excludelowpop'] = false;
$aParameters['filter_excludelowpop_value'] = false;
$aParameters['filter_column_recursive'] = false;
$aParameters['filter_pattern'] = false;
$aParameters['filter_pattern_recursive'] = false;
$aParameters['filter_truncate'] = false;
$aParameters['hideColumns'] = false;
$aParameters['hideColumnsRecursively'] = false;
$aParameters['showColumns'] = false;
$aParameters['pivotBy'] = false;
$aParameters['pivotByColumn'] = false;
$aParameters['pivotByColumnLimit'] = false;
$aParameters['disable_queued_filters'] = false;
$aParameters['disable_generic_filters'] = false;
$aParameters['expanded'] = false;
$aParameters['idDimenson'] = false;
$aParameters['format_metrics'] = false;
$aParameters['compare'] = false;
$aParameters['compareDates'] = false;
$aParameters['comparePeriods'] = false;
$aParameters['compareSegments'] = false;
$aParameters['comparisonIdSubtables'] = false;
$aParameters['invert_compare_change_compute'] = false;
$entityNames = StaticContainer::get('entities.idNames');
foreach ($entityNames as $entityName) {
if (isset($aParameters[$entityName])) {
continue;
}
$aParameters[$entityName] = false;
}
$moduleName = Proxy::getInstance()->getModuleNameFromClassName($class);
$aParameters = array_merge(array('module' => 'API', 'method' => $moduleName . '.' . $methodName), $aParameters);
foreach ($aParameters as $nameVariable => &$defaultValue) {
if (isset($knowExampleDefaultParametersValues[$nameVariable])) {
$defaultValue = $knowExampleDefaultParametersValues[$nameVariable];
} // if there isn't a default value for a given parameter,
// we need a 'know default value' or we can't generate the link
elseif ($defaultValue instanceof NoDefaultValue) {
return false;
}
}
return '?' . Url::getQueryStringFromParameters($aParameters);
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
c: Documentation For issues related to in-app product help messages, or to the Matomo knowledge base.
Projects
None yet
Milestone
For Prioritization
Development

No branches or pull requests
4 participants
@sgiehl @peterhashair @Chardonneaur @innocraft-automation