matomo-org / matomo-org/plugin-CustomAlerts

CustomAlerts API uses inconsistent parameter and response names compared to the rest of the Reporting API

Open
#250 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.