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:

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 zet requests daarom over op de huidige veldnaam.

Een verouderde queryparameter

Een queryparameter is verouderd wanneer een beter filter hem vervangt. Hij gedraagt zich op drie 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 in elke SDK, zijn vlag in 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 laat overstappen, is de Deprecation-header het enige signaal dat je ontvangt. Controleer de beschrijving van de parameter in deze referentie: een verouderde parameter begint 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 zet je requests over op 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 daarna alleen nog de huidige vorm.

Huidige verouderde onderdelen

Er is geen veldhernoeming 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 filteren elk op één kant van het bericht, en elk accepteert een telefoonnummer of een gebruikers-ID binnen het bedrijf. phone_number vond het contact in beide richtingen, dus voor een zoekopdracht waarbij de richting niet uitmaakt heb je beide filters nodig, met voor elk een apart request.