Deprecazioni

Bird depreca tre tipi diversi di elemento, e ciascuno si comporta in modo diverso. Un campo della richiesta viene rinominato, e il vecchio nome continua a funzionare insieme al nuovo. Un parametro di query viene sostituito da un filtro migliore, e continua a funzionare invariato. Una struttura del corpo della richiesta viene sostituita da una nuova struttura, e quella vecchia continua a essere accettata. In ogni caso, una richiesta che ne usa uno riceve in risposta un header Deprecation che lo segnala.

L'header

Una risposta a una richiesta che conteneva un campo, un parametro o una struttura del corpo deprecati include:

Il valore di Deprecation registra quando il vecchio nome è diventato deprecato, secondo la RFC 9745. Non annuncia una data di rimozione.

Le risposte a richieste che usano solo nomi correnti non contengono nessuno dei due header, quindi la presenza dell'header è il segnale: se non lo vedete mai, nulla di ciò che inviate è deprecato.

Nessuna data di rimozione

Bird non invia un header Sunset perché non è ancora disponibile una data di rimozione. Un nome sostituito viene rimosso solo dopo che il suo utilizzo è cessato. Bird contatta i clienti interessati prima della rimozione.

Considerate l'header Deprecation come un invito a migrare con i vostri tempi. Non avvia un conto alla rovescia per la rimozione.

Un campo della richiesta rinominato

Un campo rinominato si comporta esattamente come prima:

• Viene ancora accettato nelle richieste e scrive ancora lo stesso valore.
• Viene ancora restituito nelle risposte, insieme al nome che lo ha sostituito.
• Il nome corrente prevale se li inviate entrambi, così potete migrare un punto di chiamata alla volta senza che il vecchio nome sovrascriva il nuovo.

I nomi dei campi rinominati sono omessi da questa documentazione di riferimento, e gli SDK ufficiali espongono solo i nomi correnti. Aggiornare il vostro SDK sposta quindi le richieste sul nome di campo corrente.

Un parametro di query deprecato

Un parametro di query viene deprecato quando un filtro migliore lo sostituisce. Si comporta diversamente da un campo rinominato in tre aspetti:

• Resta pubblicato ovunque. Rimuoverlo dalla documentazione di riferimento e dagli SDK interromperebbe i chiamanti che già lo inviano, quindi mantiene la sua riga in questa documentazione di riferimento, il suo campo in ogni SDK, il suo flag nella CLI e la sua voce nello schema dello strumento MCP. Aggiornare il vostro SDK non vi fa migrare.
• Non c'è una parte nella risposta. Un parametro di query compare solo nella richiesta, quindi nulla nel corpo della risposta cambia e non c'è un nuovo nome da leggere.
• La sostituzione può non essere un singolo parametro. Un filtro viene a volte sostituito da una coppia, quindi la descrizione del parametro stesso indica cosa usare al suo posto anziché puntare a un unico successore.

Poiché l'aggiornamento non vi fa migrare, l'header Deprecation è l'unico segnale che ricevete. Controllate la descrizione del parametro in questa documentazione di riferimento: un parametro deprecato inizia con Deprecated: e indica la sua sostituzione.

Una struttura del corpo della richiesta sostituita

Gli endpoint di invio batch, POST /v1/sms/batches e POST /v1/email/batches, accettavano il batch come un semplice array JSON di primo livello. Ora accettano un oggetto il cui array messages contiene gli stessi elementi, ed è questa la struttura documentata in questa documentazione di riferimento. Una richiesta il cui corpo è ancora il semplice array continua a funzionare esattamente come prima e riceve in risposta l'header Deprecation. Gli SDK ufficiali inviano l'oggetto messages, quindi aggiornare il vostro SDK sposta le richieste sulla struttura corrente.

Migrazione

• Controllate la presenza dell'header Deprecation nelle vostre risposte.
• Individuate la richiesta che lo ha prodotto e consultate l'operazione in questa documentazione di riferimento per vedere i nomi correnti e la struttura della richiesta.
• Passate al nome o alla struttura corrente. Una volta fatto, inviate solo la forma corrente.

Deprecazioni correnti

Nessun campo rinominato è deprecato. Il numero di telefono di un contatto è phone_number e l'indirizzo email del destinatario di una verifica è email dentro to; qualsiasi altra grafia viene rifiutata come errore di validazione, in ogni operazione che li accetta.

to e from nell'elenco messaggi WhatsApp corrispondono ciascuno a un capo del messaggio, e ciascuno accetta un numero di telefono o un ID utente con ambito business. phone_number corrispondeva al contatto in entrambe le direzioni, quindi una ricerca indifferente alla direzione richiede entrambi i filtri, una richiesta ciascuno.