Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 04

API interna e pubblica

Il CMS ha due superfici API, che si somigliano nel nome e non c'entrano nulla l'una con l'altra. Confonderle è il primo errore.

1. Le due superfici

REST internaAPI pubblica
URL/api/<versione>/.../api/1.0/<endpoint>
Chi rispondeconf/gallery/api/* via kernel (Api::request)cartella fisica api/1.0/index.php
Per chiil backend e il frontend del CMS (AJAX interno)integratori esterni, macchina-macchina
Autenticazionesessione e permessi del CMSclient credentials → token Bearer
Stato nel repoereditata dall'upstream, usata dal backendscritta per JoeCMS, solo l'endpoint auth

Il conflitto è reale: /api è riservato dal kernel (vendor/wolfgan/cms/services/kernel.php instrada /api/... su Api::request), quindi un'API pubblica non è instradabile via routing_table.xml. La soluzione adottata è una cartella fisica servita direttamente da Apache.

/api è riservato solo come primo segmento: le due regole dell'API del kernel ('^/api/1.0/', '^/api(?=/|$)…') e la regola api di conf/routing_table.xml sono ancorate, come quelle delle cartelle di sistema (01 §3). Fino alla 3.1.0 non lo erano e qualsiasi path che conteneva /api finiva in Api::request() con un 404 vuoto: le API di un modulo sotto /jd/api/…, un servizio di backoffice /srv/progetto/api-rigenera, una pagina /apicoltura. Su un sito ancora alla 3.1.0 vale il vecchio consiglio: niente /api dentro i percorsi.

2. REST interna: cosa espone già

conf/gallery/api/ (instradata da conf/routing_table.xml, regola id="api"):

EndpointRestituisce
get_user, get_anagraph, get_anagraph_rel_anagraphutenti e anagrafiche
get_form, get_form_fields, get_form_type, get_form_revisiondefinizione e revisioni dei form
get_vgallery_type, get_vgallery_fields, get_extended_typelo schema dei contenuti a runtime
get_layoutstruttura del layout
get_operation, get_paymentoperazioni ed e-commerce
process_list, process_detail, process_updaterliste, dettaglio, aggiornamento
parseparsing di template
notifier/notifiche (vedi 06)

get_vgallery_type + get_vgallery_fields + get_extended_type sono la ragione per cui un generatore può essere generico: lo schema dei contenuti è leggibile a runtime, senza sapere in anticipo quali tipi esistono su quella installazione. È esattamente ciò che fa /md per la versione Markdown dei contenuti (GUIDA_INDICIZZAZIONE_AI.md).

3. API pubblica: com'è fatta

Dettaglio completo e riferimento operativo in ../api-auth.md. Qui il modello, per chi deve estenderla.

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

Il resto del percorso dopo l'endpoint arriva in $_GET["_path"] (ripulito: solo lettere, cifre, _, -, /). Serve agli endpoint che espongono più risorse — /api/1.0/app/prenotazioni/annulla — e chi non lo usa lo ignora.

Il flusso di autenticazione:

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_<...>   su ogni chiamata successiva
  • credenziali su cm_api_client, token su cm_api_token (salvato come SHA-256);
  • TTL costante JOECMS_API_TOKEN_TTL (3600s), nessun refresh token: per macchina-macchina il client si ri-autentica;
  • generazione credenziali da CLI: php install/api-credenziali.php "Nome del client".

Aggiungere un endpoint

  1. creare applets/services/api/<ep>.php;
  2. dichiararlo nel config dell'installazione, senza toccare api/1.0/index.php:
    define("JC_API_ENDPOINTS", "<ep>");          // più d'uno: "app,webhook"

    auth c'è sempre e non va elencato. Prima questo passo era una modifica al front controller, cioè al core: ogni progetto ci lasciava il nome di un suo endpoint;

  3. proteggerlo:
$ctx = joecms_api_auth();                                   // legge 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
// ... logica ...
joecms_api_json(200, array("ok" => true));

Gli helper (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) stanno in hook.php.

4. Convenzioni del contratto

Poche, ripetute ovunque: è la parte che l'integratore percepisce come "API coerente".

  • Content-Type: application/json, con fallback trasparente ai parametri form.
  • Ogni risposta ha ok booleano. Errore = {ok:false, error:"<codice o messaggio>"}.
  • Le chiavi sconosciute non sono un errore: si raccolgono in un array ignorati nella risposta. Un client che manda un campo in più non si vede rifiutare tutta la chiamata, ma se ne accorge.
  • Update parziale: negli upsert si toccano solo i campi presenti nel body. Assente ≠ vuoto.
  • Idempotenza dove è gratis: eliminare qualcosa che non c'è risponde 200 con deleted:false. Un retry del client non deve mai essere pericoloso.
  • I campi che l'API non può scrivere si dichiarano nel docblock e si ignorano in silenzio: è la superficie che protegge le invarianti del dominio.

Status HTTP, con il significato usato nell'ecosistema:

CodiceQuando
200fatto (anche per il "non c'era niente da fare")
202preso in carico, l'effetto arriva dopo (coda)
400body vuoto o non JSON, parametro mancante o non valido
401token mancante, sconosciuto o scaduto — e anche credenziali errate su /auth
403autenticato ma non autorizzato su quella risorsa
404endpoint non in whitelist
422richiesta formalmente valida ma non eseguibile nello stato corrente
429rate limit
503migration non applicata su questa installazione

Il 503 per schema mancante è un pattern che vale la pena replicare: joecms_api_has_schema() verifica le tabelle e l'endpoint risponde 503 api_schema_missing invece di andare in fatal. Un deploy fatto a metà si diagnostica da solo.

5. Trappole già pagate

  • Authorization sparisce con PHP-FPM. Servono sia la regola E=HTTP_AUTHORIZATION nell'.htaccess, sia i fallback in joecms_api_read_bearer(). Sintomo classico: funziona in locale, 401 in produzione.
  • mod_rewrite non eredita il parent: HTTPS e riscritture vanno ripetuti nell'.htaccess della cartella. mod_headers invece si somma (il CORS di root resta valido).
  • chdir($root) nel front controller: config.php usa require relativi; senza chdir il bootstrap fallisce in modo oscuro.
  • Confronto del secret con hash_equals, e 401 indistinguibile fra client inesistente e secret errato: altrimenti l'API diventa un oracolo per enumerare i client.
  • Il tenant non si accetta mai dal body. È l'errore che trasforma l'API in una porta aperta sui dati altrui.
  • use_cache(false) in cima a ogni service file: senza, il CMS può servire una risposta cachata a una chiamata autenticata.
  • Housekeeping dei token mirato: un DELETE globale su expires_at < NOW() a ogni auth diventa costoso su tabelle grandi.
  • La whitelist e la documentazione divergono in silenzio. Se l'API cresce, serve un controllo automatico che confronti whitelist, file presenti e documentazione.
  • La cartella api/ va caricata a mano nei deploy senza ZIP: è fuori dal flusso del kernel e quindi fuori dall'attenzione.

6. Dare una faccia all'API

Senza un posto dove leggere client_id e client_secret, per il cliente l'API non esiste. Il pattern collaudato è un tab nelle impostazioni del backend con:

  • credenziali, con copia / mostra / rigenera;
  • l'elenco degli endpoint disponibili;
  • la tabella dei parametri accettati generata dai campi reali di quella installazione — documentazione che non può divergere dal sistema;
  • esempi curl pronti da incollare, con l'host reale.

Il servizio di rigenerazione è di backoffice, non di API: autenticazione di sessione (checkUserRights), verifica di proprietà, poi rigenerazione. E — vedi §1 — niente api nel nome del path.