Skip to content
JoeCMS Download 3.1.5
Manual · 03

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

  1. use_cache(false) at the top. Without it, the CMS may serve a stale response. (use_cache() is defined in library/gallery/common.php.)
  2. Explicit access control: checkUserRights(false) for the session (hook.php), the Bearer token for the API, the shared secret for webhooks, is_admin for admin.
  3. The data owner is derived from the session or the token, never from the body.
  4. echo ffCommon_jsonenc($data, true) — the second parameter also sends the Content-Type: application/json header (ff/common.php:1090).
  5. 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:

AspectHow it's done
Authenticationshared secret in the query string (?secret=…) compared with hash_equals, or HMAC signature of the header if the provider exposes one
MethodPOST only; any other verb → 405
Idempotencyproviders 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%
Diagnosticsone log line per call, with outcome: hit / unauthorized / no-refs / rows:0. Without it, triage is impossible

Typical triage, with that log:

SymptomMeaning
no hitthe provider isn't calling the URL
unauthorizedthe secret doesn't match
rows:0 / no-refsit 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_id like entity_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:

CaseExecutor
opt.async = trueJobs::getInstance()->add(...) — queued, then Jobs::async("/api/jobs/tools/run")
type srvJobs::srv($path, $params) — internal service
type apiJobs::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
adminprocess_admin_toolbar(...) — the hover edit bar on the front end
cacheJobs::async("/api/cache/refresh")
notify / notifyDeliveredNotifier::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:

MethodWhat 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) and exit
  • [ ] 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)