Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 03

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

  1. use_cache(false) al principio. Sin ella, el CMS puede servir una respuesta vieja. (use_cache() está definida en library/gallery/common.php.)
  2. 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_admin para el admin.
  3. El propietario de los datos se obtiene de la sesión o del token, nunca del body.
  4. echo ffCommon_jsonenc($data, true) — el segundo parámetro envía también la cabecera Content-Type: application/json (ff/common.php:1090).
  5. exit final. 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:

AspectoCómo se hace
Autenticaciónsecret compartido en la query string (?secret=…) comparado con hash_equals, o firma HMAC de la cabecera si el proveedor la ofrece
Métodosolo POST; cualquier otro verbo → 405
Idempotencialos 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ósticouna 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íntomaSignificado
ningún hitel proveedor no está llamando a la URL
unauthorizedel secret no coincide
rows:0 / no-refsllega 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_id del tipo entidad_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:

CasoEjecutor
opt.async = trueJobs::getInstance()->add(...) — encolado, luego Jobs::async("/api/jobs/tools/run")
tipo srvJobs::srv($path, $params) — servicio interno
tipo apiJobs::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
adminprocess_admin_toolbar(...) — la barra de edición en hover en el front-end
cacheJobs::async("/api/cache/refresh")
notify / notifyDeliveredNotifier::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étodoQué 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) y exit
  • [ ] 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)