matomo-org / matomo-org/plugin-CustomAlerts
CustomAlerts API uses inconsistent parameter and response names compared to the rest of the Reporting API
- Dominant language
- PHP
- Stars
- 17
- Forks
- 24
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 7
Description
## Summary
The CustomAlerts plugin diverges from the conventions used everywhere else in the Matomo Reporting API in two ways:
1. **Singular vs plural site parameter.** Every other entity (`Goals`, `Segments`, `Annotations`, `ScheduledReports`, ...) uses `idSite` (singular, scalar). `CustomAlerts.addAlert` and `CustomAlerts.editAlert` instead require `idSites` (plural, array).
2. **camelCase vs snake_case in the response.** `CustomAlerts.getAlerts` surfaces the same field as `id_sites` (snake_case, plural, array) in the response payload, while the mutation endpoints expect `idSites` (camelCase). A consumer cannot blindly round-trip a list response back into an `editAlert` call.
## Reproduction
```bash
# 1. List alerts, observe the response key is `id_sites`
curl -s "https://demo.example.org/index.php" \
-d "module=API" \
-d "method=CustomAlerts.getAlerts" \
-d "format=JSON" \
-d "token_auth=$TOKEN"
# => [{ "idalert": 1, "id_sites": [1, 2], ... }]
# 2. Try to edit using the response keys verbatim, fails
curl -s "https://demo.example.org/index.php" \
-d "module=API" \
-d "method=CustomAlerts.editAlert" \
-d "idAlert=1" \
-d "id_sites[]=1" \
-d "format=JSON" \
-d "token_auth=$TOKEN"
# => { "result": "error", "message": "Please specify a value for idSites" }
# 3. Same call with `idSites[]=1` works
```
## Expected
Either:
- The response uses `idSites` (matching the input contract), or
- The input accepts `id_sites` as an alias.
And the `idSites` (plural) parameter should ideally accept the canonical `idSite` (singular) like the rest of the API, even if only as an alias for backwards compatibility.
## Actual
Consumers must implement a CustomAlerts-specific translation layer just to mirror the data they just read.
## Suggested fix
1. Accept both `idSite` and `idSites` on input (alias). Document `idSite` as preferred, deprecate `idSites`.
2. Return the field as `idSites` (camelCase) in `getAlerts`, keep `id_sites` as a short-term alias.
3. Tag the change in the plugin changelog so consumers can detect the version cutoff.
## Impact
Every Matomo client library has to special-case CustomAlerts. Centralizing the rename reduces consumer code across the ecosystem.
Contributor guide
No contributing guide indexed for this repository
Research direction
Trace the CustomAlerts.addAlert, CustomAlerts.editAlert, and CustomAlerts.getAlerts parameter and response definitions, then compare their naming with the other Reporting API entities. Reproduce the documented curl calls and confirm completion when compatible aliases, a consistent response name, and the requested changelog update are covered without breaking existing clients.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, backend-api-design
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100