Servicios HTTP y webhooks
Todo lo que responde datos en lugar de HTML: endpoints JSON para el front-end, orquestación de varias llamadas en una sola petición, recepción de webhooks de proveedores externos.
1. /srv/<area>/<accion>: el endpoint de proyecto
El módulo cms-common reescribe /srv/(.*) a /applets/services/$1 (modules/cms-common/conf/routing_table.xml). Por tanto:
applets/services/liste/elenco.php → POST /srv/liste/elenco
Sin esa regla /srv/... acabaría en los servicios de sistema del CMS (conf/gallery/sys/services, §3) y respondería con la página de error.
Un servicio es un archivo incluido que imprime JSON y termina. No es una clase, no tiene interfaz: la forma la garantizan las convenciones.
<?php
/**
* Lista de los elementos del usuario actual.
* Output (JSON): { ok, rows: [ ... ], error }
*/
use_cache(false); // 1
$db = ffDB_Sql::factory();
$ID = checkUserRights(false); // 2 — false = no redirigir: responde JSON
$ok = false; $rows = array(); $error = '';
if ($ID) {
// 3 — el propietario de los datos viene de la sesión, NUNCA del body
// ... lógica ...
$ok = true;
} else {
$error = 'non_autenticato';
}
echo ffCommon_jsonenc(array('ok' => $ok, 'rows' => $rows, 'error' => $error), true); // 4
exit; // 5
Las cinco reglas no negociables
use_cache(false)al principio. Sin ella, el CMS puede servir una respuesta vieja. (use_cache()está definida enlibrary/gallery/common.php.)- Control de acceso explícito:
checkUserRights(false)para la sesión (hook.php), el token Bearer para la API, el secret compartido para los webhooks,is_adminpara el admin. - El propietario de los datos se obtiene de la sesión o del token, nunca del body.
echo ffCommon_jsonenc($data, true)— el segundo parámetro envía también la cabeceraContent-Type: application/json(ff/common.php:1090).exitfinal. Sin él, el CMS continúa el ciclo de página y añade el layout HTML después del JSON.
Códigos de error estables
Conviene que error sea un código (non_autenticato, limite_raggiunto, dati_non_validi, non_trovato), no una frase: el texto visible se decide en la interfaz, y cambia con el idioma.
Endpoints compartidos con la API pública
Los endpoints de la API pública pueden ser los mismos archivos (applets/services/api/*.php), alcanzables también desde /api/1.0/<endpoint> gracias al front controller de api/1.0/index.php: una sola implementación, dos puertas de entrada. En el repo ya está applets/services/api/auth.php. Ver 04 — API pública.
2. Webhooks: un servicio con una autenticación distinta
Un webhook es un /srv/<proveedor>/webhook con cuatro diferencias respecto a un endpoint de sesión:
| Aspecto | Cómo se hace |
|---|---|
| Autenticación | secret compartido en la query string (?secret=…) comparado con hash_equals, o firma HMAC de la cabecera si el proveedor la ofrece |
| Método | solo POST; cualquier otro verbo → 405 |
| Idempotencia | los proveedores repiten los eventos: el efecto debe ser repetible. El patrón probado es incrementar un contador solo cuando la fila por destinatario pasa de 0→1 (UPDATE … SET flag=1 WHERE id=? AND flag=0 + control de affectedRows()), si no se supera el 100% |
| Diagnóstico | una línea de log por cada llamada, con resultado: hit / unauthorized / no-refs / rows:0. Sin ella, el triaje es imposible |
Triaje típico, con ese log:
| Síntoma | Significado |
|---|---|
ningún hit | el proveedor no está llamando a la URL |
unauthorized | el secret no coincide |
rows:0 / no-refs | llega pero no actualiza: las referencias del payload no corresponden a nada |
Dos trucos que ahorran horas:
- correlación autónoma: pasar al proveedor, en el envío, una referencia propia (
X-Entity-Ref-ID,tag,correlation_iddel tipoentidad_x|detalle_y) y leerla a la vuelta. Depender solo del ID del proveedor significa no poder conciliar cuando cambia el payload; - URL de callback por mensaje en lugar de la configuración en el panel del proveedor, cuando el proveedor lo permite: la URL viaja con el mensaje, y un entorno de pruebas no roba los informes de producción (o los roba, si la URL está fijada al dominio de producción: es un efecto que hay que conocer antes, no después).
⚠️ Un webhook no debe acabar en contents/ como si fuera una página: la subida del router (ver 01 §4) haría responder 200 a rutas equivocadas.
3. El bus de servicios de sistema: /srv/request
conf/gallery/sys/services/request/index.php es un orquestador: recibe en POST params un JSON de varias llamadas y las ejecuta en una sola petición, devolviendo un mapa nombre_servicio → respuesta.
{
"/srv/share/check-like": { "params": { "id": 12 } },
"/api/1.0/get-tag-list": { "params": {} },
"google.pagespeed": { "opt": { "url": "https://…" }, "params": { "url": "…" } }
}
Cómo decide qué hacer con cada entrada:
| Caso | Ejecutor |
|---|---|
opt.async = true | Jobs::getInstance()->add(...) — encolado, luego Jobs::async("/api/jobs/tools/run") |
tipo srv | Jobs::srv($path, $params) — servicio interno |
tipo api | Jobs::api($path, $params) — API interna |
URL http… | Jobs::req($url, $params, $method, $response) — llamada externa, con posibilidad de extraer un fragmento de la respuesta (response.source → response.target) |
$schema["page"]["/x"]["group"] == "shard" | system_layer_shards() — composición de fragmentos de página |
admin | process_admin_toolbar(...) — la barra de edición en hover en el front-end |
cache | Jobs::async("/api/cache/refresh") |
notify / notifyDelivered | Notifier::response() / Notifier::delivered() — ver 06 |
Para qué sirve, en la práctica: una página en caché puede seguir en caché y pedir al bus, en una sola llamada, las pocas piezas que dependen del usuario (toolbar admin, notificaciones, contadores, fragmentos personalizados). Es el motivo por el que el bus vacía page_js/page_css: la respuesta no es una página.
⚠️ Es código upstream, lleno de ramas comentadas y de partes marcadas todo. Usarlo tal cual para los casos previstos (notificaciones, toolbar, shards) es razonable; construir encima una nueva arquitectura requiere leerlo entero primero.
4. Jobs: llamar a algo sin esperarlo
vendor/hcore/jobs/Jobs.php ofrece cuatro primitivas estáticas, utilizables también fuera del bus:
| Método | Qué hace |
|---|---|
Jobs::srv($path, $params) | invoca un servicio interno y devuelve su respuesta |
Jobs::api($path, $params) | invoca un endpoint de la API interna |
Jobs::req($url, $params, $method, $response) | llamada HTTP externa, con extracción opcional de un fragmento |
Jobs::async($url, $params) | fire-and-forget: abre un socket hacia su propio host, escribe la petición y no espera la respuesta |
Jobs::async() reconstruye la URL absoluta a partir del servidor actual, propaga referer, locale, user agent y cookies. Constantes de guarda en la clase: SOCKET = 10 (sockets concurrentes), TIMEOUT = 60, ANTIFLOOD = 4 segundos entre dos ejecuciones, DELAY_SCHEDULE = 3600 para reprogramar tras un error, REPEAT = "1week".
Hay también una cola persistente (->add(), ->run(), ->ps(), ->forceRun(), ->renew()) con ejecutores por tipo (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj) y storage propio. Ver 05 — Cron, jobs y workers para cuándo conviene usarla y cuándo no.
Usos en el repo, hoy: library/gallery/system/trace.php (Jobs::async("/api/cache/refresh", …)) y el bus de servicios.
5. Checklist de un endpoint nuevo
- [ ]
use_cache(false)como primera instrucción - [ ] autenticación explícita y declarada en el comentario de cabecera
- [ ] el tenant/propietario no llega desde el body
- [ ] método HTTP verificado (una GET que escribe es un problema, no un atajo)
- [ ] salida con
ffCommon_jsonenc($data, true)yexit - [ ] errores con código estable
- [ ] si escribe: transacción o guarda de idempotencia
- [ ] si es un webhook: secret con
hash_equals, log del resultado, efecto repetible - [ ] probado sin sesión (debe responder JSON, no una página de login)