Controllo delle versioni

La versione della Partner API è indicata nell'URL. La versione attuale è:

https://partner-api.performancehub.co/partner/v1/

Criteri per le modifiche

Il Performance Hub cerca di apportare, ove possibile, modifiche aggiuntive e retrocompatibili.

Esempi di modifiche retrocompatibili:

• Aggiunta di un nuovo campo facoltativo a una richiesta.
• Aggiunta di un nuovo campo a una risposta.
• Aggiunta di un nuovo endpoint.
• Aggiunta di un nuovo valore enum, quando ci si aspetta che i client gestiscano valori sconosciuti.
• Miglioramento dei messaggi di convalida senza modificare il contratto dei codici di stato.

access_time_windows e access_time_windows_revision sono campi aggiuntivi della richiesta Member. I client esistenti che li omettono lasciano invariata l'istantanea delle Access Time Windows salvata. Questa regola sull'omissione preserva la compatibilità con gli upsert parziali; omettere i campi non equivale a inviare un array vuoto.

Esempi di modifiche non retrocompatibili:

• Rimozione o ridenominazione di un campo.
• Modifica del tipo di un campo.
• Trasformazione di un campo facoltativo della richiesta in obbligatorio.
• Rimozione di un endpoint.
• Modifica del significato di un codice di stato esistente o di un reason specifico di un dominio.

Deprecazioni

Quando è necessaria una modifica non retrocompatibile, il Performance Hub eviterà, ove possibile, di modificare direttamente la versione esistente. Introdurremo invece una nuova versione o un percorso di migrazione e comunicheremo la modifica ai partner interessati.

Gli avvisi di deprecazione possono includere:

• Una voce nel registro delle modifiche.
• Comunicazioni dirette ai partner.
• Note nella Partner Console.
• Indicazioni per la migrazione nella documentazione.

Consigli per i client

Crea client che tollerino le modifiche aggiuntive:

• Ignora i campi della risposta che non usi.
• Tratta i valori enum sconosciuti come non supportati, invece di generare un arresto anomalo.
• Evita controlli rigorosi di uguaglianza sulle risposte.
• Registra i valori non riconosciuti, così da poter aggiornare la tua integrazione in modo consapevole.

Per le partizioni Member con revisioni, come le Access Time Windows, conserva la revisione inviata e il payload normalizzato finché non conosci l'esito. Riutilizzare una revisione per un contenuto modificato genera un conflitto, mentre ripetere lo stesso contenuto è idempotente. Consulta Access Time Windows.

Specifiche OpenAPI

Usa le specifiche OpenAPI pubblicate per generare client, convalidare le richieste e monitorare nel tempo le modifiche alla struttura dell'API.

Consulta Specifiche OpenAPI.