Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 04

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 interneAPI publique
URL/api/<version>/.../api/1.0/<endpoint>
Qui répondconf/gallery/api/* via le kernel (Api::request)dossier physique api/1.0/index.php
Pour quile backend et le front-end du CMS (AJAX interne)intégrateurs externes, machine à machine
Authentificationsession et permissions du CMSclient credentials → token Bearer
État dans le dépôthé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") :

EndpointRenvoie
get_user, get_anagraph, get_anagraph_rel_anagraphutilisateurs et fiches
get_form, get_form_fields, get_form_type, get_form_revisiondéfinition et révisions des formulaires
get_vgallery_type, get_vgallery_fields, get_extended_typele schéma des contenus à l'exécution
get_layoutstructure du layout
get_operation, get_paymentopérations et e-commerce
process_list, process_detail, process_updaterlistes, détail, mise à jour
parseparsing 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 dans cm_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

  1. créer applets/services/api/<ep>.php ;
  2. le déclarer dans la config de l'installation, sans toucher à api/1.0/index.php :
    define("JC_API_ENDPOINTS", "<ep>");          // plusieurs : "app,webhook"

    auth est 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 ;

  3. 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 ok booléen. Erreur = {ok:false, error:"<code ou message>"}.
  • Les clés inconnues ne sont pas une erreur : elles sont rassemblées dans un tableau ignorati dans 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 :

CodeQuand
200fait (aussi pour « il n'y avait rien à faire »)
202pris en charge, l'effet arrive plus tard (file)
400body vide ou non JSON, paramètre manquant ou invalide
401token manquant, inconnu ou expiré — et aussi identifiants erronés sur /auth
403authentifié mais non autorisé sur cette ressource
404endpoint absent de la whitelist
422requête formellement valide mais non exécutable dans l'état actuel
429rate limit
503migration 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

  • Authorization disparaît avec PHP-FPM. Il faut à la fois la règle E=HTTP_AUTHORIZATION dans le .htaccess et les replis de joecms_api_read_bearer(). Symptôme classique : ça marche en local, 401 en production.
  • mod_rewrite n'hérite pas du parent : HTTPS et réécritures doivent être répétés dans le .htaccess du dossier. mod_headers en revanche s'additionne (le CORS de la racine reste valable).
  • chdir($root) dans le front controller : config.php utilise des require relatifs ; sans chdir le 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 DELETE global sur expires_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 curl prê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.