Per iniziare
Versioni e deprecazione
Capisci le versioni principali nell'URL, le aggiunte compatibili, gli avvisi di deprecazione e le finestre di dismissione.
Percorsi stabili per versione principale
Le integrazioni dei clienti usano una versione principale nell'URL, attualmente /api/v1. Il valore info.version di OpenAPI, basato sulla data, identifica il contratto esatto pubblicato all'interno di quella versione principale.
Modifiche compatibili
SendHQ può aggiungere, all'interno di v1, campi di richiesta facoltativi, campi di risposta, valori enum dove lo schema li consente e nuove operazioni. I client devono ignorare i campi di risposta sconosciuti ed evitare di trattare un enum come definitivamente chiuso, a meno che lo schema non lo indichi.
Modifiche incompatibili
Una modifica incompatibile a richieste, risposte, autenticazione o comportamento richiede un nuovo percorso di versione principale come /api/v2, documentazione di migrazione e una transizione annunciata. L'attuale API v1 non è deprecata.
Deprecazione e dismissione
Quando una versione viene deprecata, SendHQ documenta la sostituzione e il percorso di migrazione e restituisce le intestazioni Deprecation e Sunset dove applicabile. Le versioni deprecate restano disponibili per almeno 90 giorni dopo la data di deprecazione pubblicata, a meno che il loro funzionamento continuato non comporti un rischio urgente di sicurezza o legale.