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 query parameter 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:
| Header | Valore |
|---|---|
| Deprecation | La data in cui la deprecazione è stata annunciata, ad esempio @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
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 questo reference, e gli SDK ufficiali espongono solo i nomi correnti. Aggiornare il vostro SDK sposta quindi le richieste sul nome di campo corrente.
Un query parameter deprecato
Un query parameter viene deprecato quando un filtro migliore lo sostituisce. Si comporta diversamente da un campo rinominato in tre aspetti da conoscere:
- Resta pubblicato ovunque. Rimuoverlo dal reference e dagli SDK interromperebbe i chiamanti che già lo inviano, quindi mantiene la sua riga in questo reference, il suo campo in ogni SDK, il suo flag nel CLI e la sua voce nello schema del tool MCP. Aggiornare il vostro SDK non vi fa migrare.
- Non c'è un lato risposta. Un query parameter 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 riceverete. Controllate la descrizione del parametro in questo reference: 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 array JSON di primo livello. Ora accettano un oggetto il cui array messages contiene gli stessi elementi, che è la struttura documentata in questo reference. Una richiesta il cui corpo è ancora l'array nudo 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 questo reference per l'operazione, così da 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
| Operazione | Deprecato | Usare al suo posto |
|---|---|---|
| WhatsApp: elenco messaggi | query parameter phone_number | to o from |
| SMS ed email: creazione di un batch di messaggi | corpo della richiesta come array nudo | un oggetto con messages |
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.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione