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 interna | API pubblica | |
|---|---|---|
| URL | /api/<versione>/... | /api/1.0/<endpoint> |
| Chi risponde | conf/gallery/api/* via kernel (Api::request) | cartella fisica api/1.0/index.php |
| Per chi | il backend e il frontend del CMS (AJAX interno) | integratori esterni, macchina-macchina |
| Autenticazione | sessione e permessi del CMS | client credentials → token Bearer |
| Stato nel repo | ereditata dall'upstream, usata dal backend | scritta 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"):
| Endpoint | Restituisce |
|---|---|
get_user, get_anagraph, get_anagraph_rel_anagraph | utenti e anagrafiche |
get_form, get_form_fields, get_form_type, get_form_revision | definizione e revisioni dei form |
get_vgallery_type, get_vgallery_fields, get_extended_type | lo schema dei contenuti a runtime |
get_layout | struttura del layout |
get_operation, get_payment | operazioni ed e-commerce |
process_list, process_detail, process_updater | liste, dettaglio, aggiornamento |
parse | parsing 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 sucm_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
- creare
applets/services/api/<ep>.php; - dichiararlo nel config dell'installazione, senza toccare
api/1.0/index.php:define("JC_API_ENDPOINTS", "<ep>"); // più d'uno: "app,webhook"authc'è 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; - 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
okbooleano. Errore ={ok:false, error:"<codice o messaggio>"}. - Le chiavi sconosciute non sono un errore: si raccolgono in un array
ignoratinella 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:
| Codice | Quando |
|---|---|
| 200 | fatto (anche per il "non c'era niente da fare") |
| 202 | preso in carico, l'effetto arriva dopo (coda) |
| 400 | body vuoto o non JSON, parametro mancante o non valido |
| 401 | token mancante, sconosciuto o scaduto — e anche credenziali errate su /auth |
| 403 | autenticato ma non autorizzato su quella risorsa |
| 404 | endpoint non in whitelist |
| 422 | richiesta formalmente valida ma non eseguibile nello stato corrente |
| 429 | rate limit |
| 503 | migration 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
Authorizationsparisce con PHP-FPM. Servono sia la regolaE=HTTP_AUTHORIZATIONnell'.htaccess, sia i fallback injoecms_api_read_bearer(). Sintomo classico: funziona in locale, 401 in produzione.mod_rewritenon eredita il parent: HTTPS e riscritture vanno ripetuti nell'.htaccessdella cartella.mod_headersinvece si somma (il CORS di root resta valido).chdir($root)nel front controller:config.phpusarequirerelativi; senzachdiril 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
DELETEglobale suexpires_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
curlpronti 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.