Verouderde onderdelen
Bird markeert drie verschillende dingen als verouderd, en ze gedragen zich verschillend. Een requestveld wordt hernoemd, en de oude naam blijft werken naast de nieuwe. Een queryparameter wordt vervangen door een beter filter, en blijft ongewijzigd werken. Een request-bodystructuur wordt vervangen door een nieuwe structuur, en de oude structuur wordt nog steeds geaccepteerd. In elk geval bevat het antwoord op een request dat er een gebruikt een Deprecation-responseheader die je dat vertelt.
De header
Een antwoord op een request dat een verouderd veld, een verouderde parameter of een verouderde bodystructuur bevatte, bevat:
| Header | Waarde |
|---|---|
| Deprecation | De datum waarop de veroudering is aangekondigd, bijvoorbeeld @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
De Deprecation-waarde registreert wanneer de oude naam verouderd is verklaard, conform RFC 9745. Hij kondigt geen verwijderingsdatum aan.
Antwoorden op requests die alleen huidige namen gebruiken bevatten geen van beide headers, dus de aanwezigheid van de header is het signaal: als je hem nooit ziet, is niets wat je stuurt verouderd.
Geen verwijderingsdatum
Bird stuurt geen Sunset-header mee omdat er nog geen verwijderingsdatum beschikbaar is. Een vervangen naam wordt pas verwijderd nadat het gebruik is gestopt. Bird neemt contact op met getroffen klanten vóór verwijdering.
Beschouw de Deprecation-header als een aansporing om in je eigen tempo te migreren. Hij start geen aftelling naar verwijdering.
Een hernoemd requestveld
Een vervangen veldnaam gedraagt zich precies zoals voorheen:
- Hij wordt nog steeds geaccepteerd op requests en schrijft nog steeds dezelfde waarde.
- Hij wordt nog steeds geretourneerd in antwoorden, naast de naam die hem verving.
- De huidige naam wint als je beide stuurt, zodat je één aanroeplocatie tegelijk kunt migreren zonder dat de oude naam de nieuwe overschrijft.
Hernoemde veldnamen zijn weggelaten uit deze referentie, en de officiële SDK's tonen alleen de huidige namen. Een upgrade van je SDK verplaatst requests daarom naar de huidige veldnaam.
Een verouderde queryparameter
Een queryparameter is verouderd wanneer een beter filter hem vervangt. Hij gedraagt zich op drie noemenswaardige manieren anders dan een hernoemd veld:
- Hij blijft overal gepubliceerd. Hem verwijderen uit de referentie en de SDK's zou aanroepers breken die hem al sturen, dus hij behoudt zijn rij in deze referentie, zijn veld op elke SDK, zijn vlag op de CLI, en zijn vermelding in het MCP-toolschema. Een upgrade van je SDK migreert je niet.
- Er is geen responsekant. Een queryparameter verschijnt alleen op het request, dus er verandert niets in de responsebody en er is geen nieuwe naam om terug te lezen.
- De vervanging is niet altijd één parameter. Een filter wordt soms vervangen door een paar, dus de beschrijving van de parameter zelf noemt wat je in plaats daarvan moet gebruiken in plaats van naar één opvolger te verwijzen.
Omdat een upgrade je niet verplaatst, is de Deprecation-header het enige signaal dat je krijgt. Controleer de beschrijving van de parameter in deze referentie: een verouderde parameter opent met Deprecated: en noemt zijn vervanging.
Een vervangen request-bodystructuur
De batch-verzendendpoints, POST /v1/sms/batches en POST /v1/email/batches, accepteerden de batch oorspronkelijk als een kale JSON-array op het hoogste niveau. Ze accepteren nu een object waarvan de messages-array dezelfde items bevat, en dat is de structuur die deze referentie documenteert. Een request waarvan de body nog steeds de kale array is, blijft precies zoals voorheen werken en komt terug met de Deprecation-header. De officiële SDK's sturen het messages-object, dus een upgrade van je SDK verplaatst je requests naar de huidige structuur.
Migreren
- Let op de Deprecation-header in je antwoorden.
- Zoek het request dat hem veroorzaakte en raadpleeg deze referentie voor de operatie om de huidige namen en requeststructuur te zien.
- Stap over naar de huidige naam of structuur. Stuur alleen de huidige vorm zodra je dat hebt gedaan.
Huidige verouderde onderdelen
| Operatie | Verouderd | Gebruik in plaats daarvan |
|---|---|---|
| WhatsApp: berichten ophalen | phone_number-queryparameter | to of from |
| SMS en e-mail: een batch berichten aanmaken | kale-array-requestbody | een object met messages |
Er is geen veldhernoening verouderd. Het telefoonnummer van een contact is phone_number en het e-mailadres van een verificatie-ontvanger is email binnen to; elke andere schrijfwijze van een van beide wordt afgewezen als validatiefout, bij elke operatie die ze accepteert.
to en from op de WhatsApp-berichtenlijst komen elk overeen met één kant van het bericht, en elk accepteert een telefoonnummer of een business-scoped user-ID. phone_number kwam overeen met het contact in beide richtingen, dus een zoekopdracht die niet om richting geeft heeft beide filters nodig, één request per stuk.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integrationImplementatiegidsSend your first email
Ontvang een implementatieoverzicht