Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 04

API interna y pública

El CMS tiene dos superficies API, que se parecen en el nombre y no tienen nada que ver entre sí. Confundirlas es el primer error.

1. Las dos superficies

REST internaAPI pública
URL/api/<versión>/.../api/1.0/<endpoint>
Quién respondeconf/gallery/api/* vía kernel (Api::request)carpeta física api/1.0/index.php
Para quiénel backend y el front-end del CMS (AJAX interno)integradores externos, máquina a máquina
Autenticaciónsesión y permisos del CMSclient credentials → token Bearer
Estado en el repoheredada del upstream, usada por el backendescrita para JoeCMS, solo el endpoint auth

El conflicto es real: /api está reservado por el kernel (vendor/wolfgan/cms/services/kernel.php enruta /api/... a Api::request), así que una API pública no se puede enrutar vía routing_table.xml. La solución adoptada es una carpeta física servida directamente por Apache.

/api está reservado solo como primer segmento: las dos reglas de la API del kernel ('^/api/1.0/', '^/api(?=/|$)…') y la regla api de conf/routing_table.xml están ancladas, como las de las carpetas de sistema (01 §3). Hasta la 3.1.0 no lo estaban y cualquier ruta que contuviera /api acababa en Api::request() con un 404 vacío: las API de un módulo bajo /jd/api/…, un servicio de backoffice /srv/progetto/api-rigenera, una página /apicoltura. En un sitio todavía en la 3.1.0 vale el viejo consejo: nada de /api dentro de las rutas.

2. REST interna: qué expone ya

conf/gallery/api/ (enrutada por conf/routing_table.xml, regla id="api"):

EndpointDevuelve
get_user, get_anagraph, get_anagraph_rel_anagraphusuarios y fichas de registro
get_form, get_form_fields, get_form_type, get_form_revisiondefinición y revisiones de los formularios
get_vgallery_type, get_vgallery_fields, get_extended_typeel esquema de los contenidos en tiempo de ejecución
get_layoutestructura del layout
get_operation, get_paymentoperaciones y e-commerce
process_list, process_detail, process_updaterlistas, detalle, actualización
parseparsing de plantillas
notifier/notificaciones (ver 06)

get_vgallery_type + get_vgallery_fields + get_extended_type son la razón por la que un generador puede ser genérico: el esquema de los contenidos se puede leer en tiempo de ejecución, sin saber de antemano qué tipos existen en esa instalación. Es exactamente lo que hace /md para la versión Markdown de los contenidos (GUIDA_INDICIZZAZIONE_AI.md).

3. API pública: cómo está hecha

Detalle completo y referencia operativa en ../api-auth.md. Aquí el modelo, para quien tenga que ampliarla.

GET/POST /api/1.0/<endpoint>[/<recurso>/…]
   └─ api/1.0/.htaccess      HTTPS + Authorization → PHP-FPM
                             rewrite ?_ep=<endpoint>[&_path=<recurso/…>]
        ▼
   api/1.0/index.php         bootstrap mínimo (livello-errori, config, autoload, cache, ff/main, hook)
        ├─ whitelist: "auth" + JC_API_ENDPOINTS
        └─ include applets/services/api/<endpoint>.php

El resto de la ruta tras el endpoint llega en $_GET["_path"] (limpio: solo letras, cifras, _, -, /). Sirve a los endpoints que exponen varios recursos — /api/1.0/app/reservas/anular — y quien no lo usa lo ignora.

El flujo de autenticación:

POST /api/1.0/auth  {client_id, client_secret}
   → {ok, token_type:"Bearer", access_token:"joe_<64hex>", expires_in:3600, expires_at}
   → Authorization: Bearer joe_<...>   en cada llamada siguiente
  • credenciales en cm_api_client, tokens en cm_api_token (guardado como SHA-256);
  • TTL constante JOECMS_API_TOKEN_TTL (3600s), sin refresh token: en máquina a máquina el cliente se vuelve a autenticar;
  • generación de credenciales desde CLI: php install/api-credenziali.php "Nombre del cliente".

Añadir un endpoint

  1. crear applets/services/api/<ep>.php;
  2. declararlo en el config de la instalación, sin tocar api/1.0/index.php:
    define("JC_API_ENDPOINTS", "<ep>");          // más de uno: "app,webhook"

    auth siempre está y no hace falta listarlo. Antes este paso era una modificación del front controller, es decir del core: cada proyecto dejaba ahí el nombre de uno de sus endpoints;

  3. protegerlo:
$ctx = joecms_api_auth();                                   // lee Authorization: Bearer
if (!$ctx) { joecms_api_json(401, array("ok" => false, "error" => "unauthorized")); }

$id_client = $ctx["ID_client"];
$body      = joecms_api_body();                             // JSON, fallback $_POST
// ... lógica ...
joecms_api_json(200, array("ok" => true));

Los helpers (joecms_api_has_schema, joecms_api_genera_credenziali, joecms_api_client_by_credentials, joecms_api_crea_token, joecms_api_auth, joecms_api_read_bearer, joecms_api_body, joecms_api_json, joecms_api_uuid) están en hook.php.

4. Convenciones del contrato

Pocas, repetidas en todas partes: es la parte que el integrador percibe como "API coherente".

  • Content-Type: application/json, con fallback transparente a los parámetros de formulario.
  • Toda respuesta tiene ok booleano. Error = {ok:false, error:"<código o mensaje>"}.
  • Las claves desconocidas no son un error: se recogen en un array ignorati en la respuesta. Un cliente que envía un campo de más no ve rechazada toda la llamada, pero se da cuenta.
  • Actualización parcial: en los upsert solo se tocan los campos presentes en el body. Ausente ≠ vacío.
  • Idempotencia donde sale gratis: eliminar algo que no existe responde 200 con deleted:false. Un reintento del cliente nunca debe ser peligroso.
  • Los campos que la API no puede escribir se declaran en el docblock y se ignoran en silencio: es la superficie que protege las invariantes del dominio.

Status HTTP, con el significado usado en el ecosistema:

CódigoCuándo
200hecho (también para "no había nada que hacer")
202aceptado, el efecto llega después (cola)
400body vacío o no JSON, parámetro ausente o no válido
401token ausente, desconocido o caducado — y también credenciales erróneas en /auth
403autenticado pero no autorizado sobre ese recurso
404endpoint no presente en la whitelist
422petición formalmente válida pero no ejecutable en el estado actual
429rate limit
503migración no aplicada en esta instalación

El 503 por esquema ausente es un patrón que merece la pena replicar: joecms_api_has_schema() verifica las tablas y el endpoint responde 503 api_schema_missing en lugar de acabar en un fatal. Un despliegue hecho a medias se diagnostica solo.

5. Trampas ya pagadas

  • Authorization desaparece con PHP-FPM. Hacen falta tanto la regla E=HTTP_AUTHORIZATION en el .htaccess como los fallbacks de joecms_api_read_bearer(). Síntoma clásico: funciona en local, 401 en producción.
  • mod_rewrite no hereda del padre: HTTPS y reescrituras hay que repetirlas en el .htaccess de la carpeta. mod_headers en cambio se suma (el CORS de la raíz sigue valiendo).
  • chdir($root) en el front controller: config.php usa require relativos; sin chdir el bootstrap falla de forma oscura.
  • Comparación del secret con hash_equals, y 401 indistinguible entre cliente inexistente y secret erróneo: si no, la API se convierte en un oráculo para enumerar los clientes.
  • El tenant nunca se acepta desde el body. Es el error que convierte la API en una puerta abierta a los datos ajenos.
  • use_cache(false) al principio de cada service file: sin él, el CMS puede servir una respuesta en caché a una llamada autenticada.
  • Limpieza de tokens dirigida: un DELETE global sobre expires_at < NOW() en cada auth se vuelve costoso en tablas grandes.
  • La whitelist y la documentación divergen en silencio. Si la API crece, hace falta un control automático que compare whitelist, archivos presentes y documentación.
  • La carpeta api/ hay que subirla a mano en los despliegues sin ZIP: está fuera del flujo del kernel y por tanto fuera de la atención.

6. Dar una cara a la API

Sin un lugar donde leer client_id y client_secret, para el cliente la API no existe. El patrón probado es una pestaña en los ajustes del backend con:

  • credenciales, con copiar / mostrar / regenerar;
  • la lista de los endpoints disponibles;
  • la tabla de los parámetros aceptados generada a partir de los campos reales de esa instalación — documentación que no puede divergir del sistema;
  • ejemplos curl listos para pegar, con el host real.

El servicio de regeneración es de backoffice, no de API: autenticación de sesión (checkUserRights), verificación de propiedad, luego regeneración. Y — ver §1 — nada de api en el nombre de la ruta.