API interne et publique
Le CMS a deux surfaces API, qui se ressemblent par le nom et n'ont rien à voir l'une avec l'autre. Les confondre est la première erreur.
1. Les deux surfaces
| REST interne | API publique | |
|---|---|---|
| URL | /api/<version>/... | /api/1.0/<endpoint> |
| Qui répond | conf/gallery/api/* via le kernel (Api::request) | dossier physique api/1.0/index.php |
| Pour qui | le backend et le front-end du CMS (AJAX interne) | intégrateurs externes, machine à machine |
| Authentification | session et permissions du CMS | client credentials → token Bearer |
| État dans le dépôt | héritée de l'upstream, utilisée par le backend | écrite pour JoeCMS, seulement l'endpoint auth |
Le conflit est réel : /api est réservé par le kernel (vendor/wolfgan/cms/services/kernel.php route /api/... vers Api::request), donc une API publique ne peut pas être routée via routing_table.xml. La solution adoptée est un dossier physique servi directement par Apache.
/api n'est réservé que comme premier segment : les deux règles de l'API du kernel ('^/api/1.0/', '^/api(?=/|$)…') et la règle api de conf/routing_table.xml sont ancrées, comme celles des dossiers système (01 §3). Jusqu'à la 3.1.0 elles ne l'étaient pas et tout chemin contenant /api finissait dans Api::request() avec un 404 vide : les API d'un module sous /jd/api/…, un service de backoffice /srv/progetto/api-rigenera, une page /apicoltura. Sur un site encore en 3.1.0, l'ancien conseil vaut toujours : pas de /api dans les chemins.
2. REST interne : ce qu'elle expose déjà
conf/gallery/api/ (routée par conf/routing_table.xml, règle id="api") :
| Endpoint | Renvoie |
|---|---|
get_user, get_anagraph, get_anagraph_rel_anagraph | utilisateurs et fiches |
get_form, get_form_fields, get_form_type, get_form_revision | définition et révisions des formulaires |
get_vgallery_type, get_vgallery_fields, get_extended_type | le schéma des contenus à l'exécution |
get_layout | structure du layout |
get_operation, get_payment | opérations et e-commerce |
process_list, process_detail, process_updater | listes, détail, mise à jour |
parse | parsing de templates |
notifier/ | notifications (voir 06) |
get_vgallery_type + get_vgallery_fields + get_extended_type sont la raison pour laquelle un générateur peut être générique : le schéma des contenus est lisible à l'exécution, sans savoir à l'avance quels types existent sur cette installation. C'est exactement ce que fait /md pour la version Markdown des contenus (GUIDA_INDICIZZAZIONE_AI.md).
3. API publique : comment elle est faite
Détail complet et référence opérationnelle dans ../api-auth.md. Ici le modèle, pour qui doit l'étendre.
GET/POST /api/1.0/<endpoint>[/<ressource>/…]
└─ api/1.0/.htaccess HTTPS + Authorization → PHP-FPM
rewrite ?_ep=<endpoint>[&_path=<ressource/…>]
▼
api/1.0/index.php bootstrap minimal (livello-errori, config, autoload, cache, ff/main, hook)
├─ whitelist : "auth" + JC_API_ENDPOINTS
└─ include applets/services/api/<endpoint>.php
Le reste du chemin après l'endpoint arrive dans $_GET["_path"] (nettoyé : seulement lettres, chiffres, _, -, /). Il sert aux endpoints qui exposent plusieurs ressources — /api/1.0/app/reservations/annuler — et ceux qui ne l'utilisent pas l'ignorent.
Le flux d'authentification :
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_<...> sur chaque appel suivant
- identifiants dans
cm_api_client, tokens danscm_api_token(enregistré en SHA-256) ; - TTL constant
JOECMS_API_TOKEN_TTL(3600 s), pas de refresh token : en machine à machine le client se ré-authentifie ; - génération des identifiants en CLI :
php install/api-credenziali.php "Nom du client".
Ajouter un endpoint
- créer
applets/services/api/<ep>.php; - le déclarer dans la config de l'installation, sans toucher à
api/1.0/index.php:define("JC_API_ENDPOINTS", "<ep>"); // plusieurs : "app,webhook"authest toujours présent et n'a pas à être listé. Avant, cette étape était une modification du front controller, c'est-à-dire du core : chaque projet y laissait le nom de l'un de ses endpoints ; - le protéger :
$ctx = joecms_api_auth(); // lit Authorization: Bearer
if (!$ctx) { joecms_api_json(401, array("ok" => false, "error" => "unauthorized")); }
$id_client = $ctx["ID_client"];
$body = joecms_api_body(); // JSON, repli sur $_POST
// ... logique ...
joecms_api_json(200, array("ok" => true));
Les 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) sont dans hook.php.
4. Conventions du contrat
Peu nombreuses, répétées partout : c'est la partie que l'intégrateur perçoit comme une « API cohérente ».
Content-Type: application/json, avec repli transparent sur les paramètres de formulaire.- Toute réponse a un
okbooléen. Erreur ={ok:false, error:"<code ou message>"}. - Les clés inconnues ne sont pas une erreur : elles sont rassemblées dans un tableau
ignoratidans la réponse. Un client qui envoie un champ de trop ne voit pas tout l'appel refusé, mais il s'en aperçoit. - Mise à jour partielle : dans les upserts on ne touche que les champs présents dans le body. Absent ≠ vide.
- Idempotence là où elle est gratuite : supprimer quelque chose qui n'existe pas répond 200 avec
deleted:false. Une nouvelle tentative du client ne doit jamais être dangereuse. - Les champs que l'API ne peut pas écrire se déclarent dans le docblock et s'ignorent en silence : c'est la surface qui protège les invariants du domaine.
Statuts HTTP, avec le sens utilisé dans l'écosystème :
| Code | Quand |
|---|---|
| 200 | fait (aussi pour « il n'y avait rien à faire ») |
| 202 | pris en charge, l'effet arrive plus tard (file) |
| 400 | body vide ou non JSON, paramètre manquant ou invalide |
| 401 | token manquant, inconnu ou expiré — et aussi identifiants erronés sur /auth |
| 403 | authentifié mais non autorisé sur cette ressource |
| 404 | endpoint absent de la whitelist |
| 422 | requête formellement valide mais non exécutable dans l'état actuel |
| 429 | rate limit |
| 503 | migration non appliquée sur cette installation |
Le 503 pour schéma manquant est un modèle qui mérite d'être reproduit : joecms_api_has_schema() vérifie les tables et l'endpoint répond 503 api_schema_missing au lieu de tomber en fatal. Un déploiement fait à moitié se diagnostique tout seul.
5. Pièges déjà payés
Authorizationdisparaît avec PHP-FPM. Il faut à la fois la règleE=HTTP_AUTHORIZATIONdans le.htaccesset les replis dejoecms_api_read_bearer(). Symptôme classique : ça marche en local, 401 en production.mod_rewriten'hérite pas du parent : HTTPS et réécritures doivent être répétés dans le.htaccessdu dossier.mod_headersen revanche s'additionne (le CORS de la racine reste valable).chdir($root)dans le front controller :config.phputilise desrequirerelatifs ; sanschdirle bootstrap échoue de façon obscure.- Comparaison du secret avec
hash_equals, et 401 indiscernable entre client inexistant et secret erroné : sinon l'API devient un oracle pour énumérer les clients. - Le tenant ne s'accepte jamais depuis le body. C'est l'erreur qui transforme l'API en porte ouverte sur les données des autres.
use_cache(false)en tête de chaque service file : sans lui, le CMS peut servir une réponse en cache à un appel authentifié.- Nettoyage ciblé des tokens : un
DELETEglobal surexpires_at < NOW()à chaque auth devient coûteux sur de grandes tables. - La whitelist et la documentation divergent en silence. Si l'API grandit, il faut un contrôle automatique qui compare whitelist, fichiers présents et documentation.
- Le dossier
api/doit être envoyé à la main dans les déploiements sans ZIP : il est hors du flux du kernel et donc hors de l'attention.
6. Donner un visage à l'API
Sans un endroit où lire client_id et client_secret, pour le client l'API n'existe pas. Le modèle éprouvé est un onglet dans les réglages du backend avec :
- les identifiants, avec copier / afficher / régénérer ;
- la liste des endpoints disponibles ;
- la table des paramètres acceptés générée à partir des champs réels de cette installation — une documentation qui ne peut pas diverger du système ;
- des exemples
curlprêts à coller, avec l'hôte réel.
Le service de régénération est de backoffice, pas d'API : authentification de session (checkUserRights), vérification de propriété, puis régénération. Et — voir §1 — pas de api dans le nom du chemin.