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 interna | API pública | |
|---|---|---|
| URL | /api/<versión>/... | /api/1.0/<endpoint> |
| Quién responde | conf/gallery/api/* vía kernel (Api::request) | carpeta física api/1.0/index.php |
| Para quién | el backend y el front-end del CMS (AJAX interno) | integradores externos, máquina a máquina |
| Autenticación | sesión y permisos del CMS | client credentials → token Bearer |
| Estado en el repo | heredada del upstream, usada por el backend | escrita 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"):
| Endpoint | Devuelve |
|---|---|
get_user, get_anagraph, get_anagraph_rel_anagraph | usuarios y fichas de registro |
get_form, get_form_fields, get_form_type, get_form_revision | definición y revisiones de los formularios |
get_vgallery_type, get_vgallery_fields, get_extended_type | el esquema de los contenidos en tiempo de ejecución |
get_layout | estructura del layout |
get_operation, get_payment | operaciones y e-commerce |
process_list, process_detail, process_updater | listas, detalle, actualización |
parse | parsing 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 encm_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
- crear
applets/services/api/<ep>.php; - 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"authsiempre 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; - 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
okbooleano. Error ={ok:false, error:"<código o mensaje>"}. - Las claves desconocidas no son un error: se recogen en un array
ignoratien 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ódigo | Cuándo |
|---|---|
| 200 | hecho (también para "no había nada que hacer") |
| 202 | aceptado, el efecto llega después (cola) |
| 400 | body vacío o no JSON, parámetro ausente o no válido |
| 401 | token ausente, desconocido o caducado — y también credenciales erróneas en /auth |
| 403 | autenticado pero no autorizado sobre ese recurso |
| 404 | endpoint no presente en la whitelist |
| 422 | petición formalmente válida pero no ejecutable en el estado actual |
| 429 | rate limit |
| 503 | migració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
Authorizationdesaparece con PHP-FPM. Hacen falta tanto la reglaE=HTTP_AUTHORIZATIONen el.htaccesscomo los fallbacks dejoecms_api_read_bearer(). Síntoma clásico: funciona en local, 401 en producción.mod_rewriteno hereda del padre: HTTPS y reescrituras hay que repetirlas en el.htaccessde la carpeta.mod_headersen cambio se suma (el CORS de la raíz sigue valiendo).chdir($root)en el front controller:config.phpusarequirerelativos; sinchdirel 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
DELETEglobal sobreexpires_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
curllistos 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.