Versioni e deprecazioni

Questa politica vale per tutta l’API di integrazione: REST API v1, widget, webhook in uscita e in entrata, SCIM 2.0. Le chiamate interne usate dai portali Core, Workspace e Desk non sono coperte e possono cambiare in qualsiasi momento: non usarle nelle integrazioni.

Versioni principali

• La versione principale è nel percorso: /api/v1/…. Ogni risposta di /api/v1 contiene X-Exo-API-Version: 1.
• La v1 è stabile. Dentro la v1 facciamo solo modifiche compatibili:
  • nuovi endpoint, nuovi campi facoltativi nelle richieste, nuovi parametri di query;
  • nuovi campi nelle risposte: il tuo client deve ignorare quelli che non conosce;
  • nuovi tipi di evento webhook: il tuo sistema deve ignorare quelli che non conosce;
  • nuovi codici di errore: gestisci quelli sconosciuti in base allo stato HTTP;
  • nuove intestazioni facoltative.
• Una modifica incompatibile richiede una nuova versione principale (/api/v2). È incompatibile rimuovere o rinominare un campo, un endpoint o un evento, cambiare un tipo, rendere obbligatorio un campo facoltativo o cambiare l’autenticazione.
• Quando esce una nuova versione principale, la precedente resta disponibile per almeno 12 mesi.

Deprecazioni

• Una funzione deprecata continua a funzionare per almeno 6 mesi dall’annuncio.
• Le risposte che usano una funzione deprecata contengono:
  • Deprecation: @<unix-seconds>: quando è stata annunciata la deprecazione (RFC 9745);
  • Sunset: <HTTP-date>: quando la funzione smetterà di funzionare (RFC 8594);
  • Link: <url>; rel="deprecation": la guida alla migrazione.
• Ogni deprecazione è nel changelog ed è segnata come deprecated nella specifica OpenAPI.

Deprecazioni in corso

Funzione	Annunciata	Smette di funzionare	Cosa usare
Chiavi API nh_…	1 novembre 2026	30 giugno 2027	Chiavi nhk.<keyid>.<secret>
Firma X-NH-Signature sui webhook in uscita	1 novembre 2026	30 giugno 2027	X-Exo-Signature con X-Exo-Timestamp
Firma X-NH-Connector-Signature sui webhook in entrata	1 novembre 2026	30 giugno 2027	X-Exo-Signature con X-Exo-Timestamp
Campi event, timestamp, source nel corpo dei webhook	1 novembre 2026	30 giugno 2027	type, created_at, data

Specifica e changelog

• La specifica OpenAPI è il contratto. La sua versione segue il semantic versioning 1.MINOR.PATCH: MINOR cresce per le aggiunte compatibili, PATCH per le sole correzioni di documentazione.
• Ogni modifica all’API aggiorna la versione della specifica e aggiunge una voce al changelog.