HTTP services and webhooks
Everything that answers data instead of HTML: JSON endpoints for the front end, orchestrating several calls in a single request, receiving webhooks from external providers.
1. /srv/<area>/<action>: the project endpoint
The cms-common module rewrites /srv/(.*) to /applets/services/$1 (modules/cms-common/conf/routing_table.xml). So:
applets/services/liste/elenco.php → POST /srv/liste/elenco
Without that rule /srv/... would end up in the CMS's system services (conf/gallery/sys/services, §3) and answer with the error page.
A service is an included file that prints JSON and terminates. It's not a class, it has no interface: its shape is guaranteed by conventions.
<?php
/**
* List of the current user's items.
* Output (JSON): { ok, rows: [ ... ], error }
*/
use_cache(false); // 1
$db = ffDB_Sql::factory();
$ID = checkUserRights(false); // 2 — false = don't redirect: answer JSON
$ok = false; $rows = array(); $error = '';
if ($ID) {
// 3 — the data owner comes from the session, NEVER from the body
// ... logic ...
$ok = true;
} else {
$error = 'non_autenticato';
}
echo ffCommon_jsonenc(array('ok' => $ok, 'rows' => $rows, 'error' => $error), true); // 4
exit; // 5
The five non-negotiable rules
use_cache(false)at the top. Without it, the CMS may serve a stale response. (use_cache()is defined inlibrary/gallery/common.php.)- Explicit access control:
checkUserRights(false)for the session (hook.php), the Bearer token for the API, the shared secret for webhooks,is_adminfor admin. - The data owner is derived from the session or the token, never from the body.
echo ffCommon_jsonenc($data, true)— the second parameter also sends theContent-Type: application/jsonheader (ff/common.php:1090).- Final
exit. Without it, the CMS continues the page cycle and appends the HTML layout after the JSON.
Stable error codes
error should be a code (non_autenticato, limite_raggiunto, dati_non_validi, non_trovato), not a sentence: the visible text is decided on the interface side, and changes with the language.
Endpoints shared with the public API
Public API endpoints can be the same files (applets/services/api/*.php), also reachable from /api/1.0/<endpoint> thanks to the front controller in api/1.0/index.php: one implementation, two entry doors. The repo already has applets/services/api/auth.php. See 04 — Public API.
2. Webhooks: a service with different authentication
A webhook is a /srv/<provider>/webhook with four differences from a session endpoint:
| Aspect | How it's done |
|---|---|
| Authentication | shared secret in the query string (?secret=…) compared with hash_equals, or HMAC signature of the header if the provider exposes one |
| Method | POST only; any other verb → 405 |
| Idempotency | providers repeat events: the effect must be repeatable. The proven pattern is to increment a counter only when the per-recipient row transitions 0→1 (UPDATE … SET flag=1 WHERE id=? AND flag=0 + checking affectedRows()), otherwise you go past 100% |
| Diagnostics | one log line per call, with outcome: hit / unauthorized / no-refs / rows:0. Without it, triage is impossible |
Typical triage, with that log:
| Symptom | Meaning |
|---|---|
no hit | the provider isn't calling the URL |
unauthorized | the secret doesn't match |
rows:0 / no-refs | it arrives but doesn't update: the references in the payload match nothing |
Two tricks that save hours:
- self-contained correlation: pass the provider, when sending, a reference of your own (
X-Entity-Ref-ID,tag,correlation_idlikeentity_x|detail_y) and read it on the way back. Relying only on the provider's ID means you can't reconcile when the payload changes; - per-message callback URL instead of configuring it in the provider's dashboard, when the provider allows it: the URL travels with the message, and a test environment doesn't steal production's reports (or does steal them, if the URL is hard-wired to the production domain: an effect to know about before, not after).
⚠️ A webhook must not end up in contents/ as if it were a page: the router walk-up (see 01 §4) would make wrong paths answer 200.
3. The system service bus: /srv/request
conf/gallery/sys/services/request/index.php is an orchestrator: it receives in POST params a JSON of several calls and executes them in a single request, returning a map service_name → response.
{
"/srv/share/check-like": { "params": { "id": 12 } },
"/api/1.0/get-tag-list": { "params": {} },
"google.pagespeed": { "opt": { "url": "https://…" }, "params": { "url": "…" } }
}
How it decides what to do with each entry:
| Case | Executor |
|---|---|
opt.async = true | Jobs::getInstance()->add(...) — queued, then Jobs::async("/api/jobs/tools/run") |
type srv | Jobs::srv($path, $params) — internal service |
type api | Jobs::api($path, $params) — internal API |
URL http… | Jobs::req($url, $params, $method, $response) — external call, with the option to extract a fragment from the response (response.source → response.target) |
$schema["page"]["/x"]["group"] == "shard" | system_layer_shards() — composing page fragments |
admin | process_admin_toolbar(...) — the hover edit bar on the front end |
cache | Jobs::async("/api/cache/refresh") |
notify / notifyDelivered | Notifier::response() / Notifier::delivered() — see 06 |
What it's for, in practice: a cached page can stay cached and ask the bus, in a single call, for the few pieces that depend on the user (admin toolbar, notifications, counters, personalised fragments). That's why the bus clears page_js/page_css: the response is not a page.
⚠️ It's upstream code, full of commented-out branches and parts marked todo. Using it as-is for the intended cases (notifications, toolbar, shards) is reasonable; building a new architecture on top of it requires reading it in full first.
4. Jobs: calling something without waiting for it
vendor/hcore/jobs/Jobs.php offers four static primitives, usable outside the bus too:
| Method | What it does |
|---|---|
Jobs::srv($path, $params) | invokes an internal service and returns its response |
Jobs::api($path, $params) | invokes an internal API endpoint |
Jobs::req($url, $params, $method, $response) | external HTTP call, with optional fragment extraction |
Jobs::async($url, $params) | fire-and-forget: opens a socket to its own host, writes the request and doesn't wait for the response |
Jobs::async() rebuilds the absolute URL from the current server, propagates referer, locale, user agent and cookies. Guard constants in the class: SOCKET = 10 (concurrent sockets), TIMEOUT = 60, ANTIFLOOD = 4 seconds between two runs, DELAY_SCHEDULE = 3600 for rescheduling after an error, REPEAT = "1week".
There's also a persistent queue (->add(), ->run(), ->ps(), ->forceRun(), ->renew()) with executors per type (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj) and its own storage. See 05 — Cron, jobs and workers for when it's worth using and when not.
Uses in the repo today: library/gallery/system/trace.php (Jobs::async("/api/cache/refresh", …)) and the service bus.
5. Checklist for a new endpoint
- [ ]
use_cache(false)as the first statement - [ ] explicit authentication, declared in the header comment
- [ ] the tenant/owner does not come from the body
- [ ] HTTP method verified (a GET that writes is a problem, not a shortcut)
- [ ] output with
ffCommon_jsonenc($data, true)andexit - [ ] errors with a stable code
- [ ] if it writes: transaction or idempotency guard
- [ ] if it's a webhook: secret with
hash_equals, outcome log, repeatable effect - [ ] tested without a session (it must answer JSON, not a login page)