Depreciere și retragere
O operație depreciată rămâne disponibilă, dar nu mai este recomandată pentru integrări noi. Retragerea marchează încetarea disponibilității ei.
Anunțuri de depreciere
Pentru fiecare depreciere, vom publica elementele afectate, pașii de migrare și data retragerii, dacă este stabilită. Deprecierea poate viza o operație sau un câmp, independent de lansarea unei versiuni majore a API-ului.
Headere HTTP
Pentru operațiile depreciate, vom semnala schimbarea prin următoarele headere de răspuns, conform RFC 9745 și RFC 8594:
| Header | Descriere | Format |
|---|---|---|
Deprecation |
Data de la care operația este depreciată. | Timestamp Unix în secunde, precedat de @. |
Sunset |
Data planificată a retragerii. Este inclus numai dacă termenul este stabilit. | HTTP-date, în GMT. |
Link |
Adresa anunțului de depreciere și a instrucțiunilor de migrare. | <URL>; rel="deprecation". |
Exemplu de răspuns pentru o operație depreciată; datele sunt ilustrative:
HTTP/1.1 200 OK
Deprecation: @1790812800
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Link: <https://api.example.com/docs/migrare>; rel="deprecation"; type="text/html"
În acest exemplu, operația este depreciată de la 1 octombrie 2026, iar retragerea este programată pentru 1 octombrie 2027.
Verifică aceste headere în răspunsuri și urmează instrucțiunile din Link pentru a migra înainte de data Sunset. Dacă Sunset lipsește, urmărește anunțul pentru actualizarea termenului.
Retragerea unei operații
După retragerea definitivă, apelurile către endpoint vor primi 410 Gone, cu detaliile erorii în format application/problem+json. Actualizează integrarea conform instrucțiunilor de migrare; repetarea aceleiași cereri nu rezolvă eroarea.
Deprecierea unui câmp
Câmpurile depreciate vor fi marcate în referința API prin deprecated: true. Descrierea câmpului și anunțul de migrare vor indica înlocuitorul și condițiile retragerii. Deprecierea unui câmp nu marchează întregul endpoint ca depreciat.