Versionamento

L’API v1 è congelata dal lancio. Il codice scritto per essa continua a funzionare: l’API si arricchisce di endpoint e campi, e non perde nulla.

Cosa può cambiare nella v1

• Nuovi endpoint, e nuovi campi e opzioni facoltativi nelle richieste, disattivati per impostazione predefinita.
• Nuovi campi nelle risposte e negli eventi dei webhook. Ignora i campi che non conosci.
• Nuovi codici di errore, solo per nuove funzioni; una richiesta esistente non riceve mai un nuovo codice per un motivo già noto.
• Nuovi tipi di eventi webhook, inviati solo agli endpoint che li richiedono.
• I messaggi di errore, che sono per le persone: basa la logica sul codice, mai sul messaggio.
• Limiti più alti, più formati, risposte più rapide.

Cosa non cambia mai nella v1

• Il percorso o il metodo di un endpoint, o il significato dei suoi campi e delle sue risposte.
• Il nome o il tipo di un campo, un valore predefinito, o lo stato e il significato di un codice di errore.
• Cosa conta come una marcatura, come indicato nella pagina dei prezzi, senza preavviso ai clienti esistenti.
• Lo schema di firma dei webhook (Kennmarq-Signature) e i formati del registro di trasparenza.

Una modifica incompatibile

Arriverebbe come v2, con percorsi propri, annunciata con almeno 12 mesi di anticipo nelle note di rilascio e via email ai proprietari di ogni organizzazione. La v1 continua a rispondere almeno per quei 12 mesi. La correzione di un problema di sicurezza è l’unica eccezione: se una richiesta così com’è non è sicura, la cambiamo subito e lo diciamo nelle note di rilascio.

OpenAPI

La v1 è descritta in un documento OpenAPI 3.1 su https://api.kennmarq.com/v1/openapi.json, per i generatori di client e gli strumenti API. Elenca tutti gli endpoint, i campi e i codici di errore di questo riferimento.