API versiyalaşdırması və istifadədən çıxarılma

REST API əsas versiyasını yolda daşıyır: /api/v1. Bir əsas versiya daxilində API yalnız mövcud müştəri proqramlarının işləməyə davam etdiyi şəkildə dəyişir. Müştəri proqramını poza bilən dəyişiklik qüvvəyə minməzdən ən azı 6 ay əvvəl elan edilir: API istinadında, API dəyişiklik jurnalında və təsirlənən əməliyyatın hər cavabının başlıqlarında.

Bu siyasət 2026-10-18 tarixindən qüvvədədir. Ümumi istifadəyə verilməzdən əvvəl edilən dəyişikliklər bildiriş müddətinə tabe deyildi. Onlar API dəyişiklik jurnalında sadalanır.

Yoldakı versiyaKeçidi kopyalayın

https://<api-host>/api/v1

• <api-host>: API-nin host adı.

Yeni əsas versiya v1 ilə yanaşı, /api/v2 kimi öz yolunda təqdim olunur. v1 əlçatan qalır və v1 üzərində uyğunluğu pozan dəyişiklik yenə də ən azı 6 ay əvvəl bildiriş tələb edir.

Geriyə uyğun dəyişikliklərKeçidi kopyalayın

Bu dəyişikliklər v1 daxilində istənilən vaxt edilə bilər. Müştəri proqramınızı elə qurun ki, onlar baş verdikdə də işləməyə davam etsin:

Uyğunluğu pozan dəyişikliklərKeçidi kopyalayın

Bu dəyişikliklər aşağıdakı istifadədən çıxarılma prosesi olmadan heç vaxt əməliyyata tətbiq edilmir:

• Əməliyyatı və ya yolu silmək.
• Məcburi parametr və ya məcburi sorğu sahəsi əlavə etmək, yaxud istəyə bağlı parametri və ya sahəni məcburi etmək.
• Sahənin və ya parametrin tipini dəyişmək.
• Sorğunun enum siyahısından dəyəri silmək, yaxud daha qısa maksimal uzunluq, daha kiçik maksimum, daha az element və ya yeni şablon kimi yoxlamanı sərtləşdirmək.
• Cavab sahəsini silmək, yaxud onu istəyə bağlı və ya null ola bilən etmək.
• Uğurlu status kodunu və ya media tipini silmək.
• Əməliyyatın əvvəllər tələb etmədiyi token miqyasını (scope) tələb etmək, yaxud istənilən birinin kifayət etdiyi miqyaslar dəstindən miqyas çıxarmaq.
• API tokenlərini (API token) və xidmət hesabı (service account) açarlarını qəbul edən əməliyyatda onları rədd edərək əməliyyatı yalnız konsol sessiyasında işləyən etmək.

Uyğunluğu pozan dəyişiklik necə elan edilirKeçidi kopyalayın

Uyğunluğu pozan dəyişiklik qüvvəyə minməzdən ən azı 6 ay əvvəl:

• Əməliyyat API istinadında və https://<api-host>/openapi.json ünvanındakı OpenAPI sənədində istifadədən çıxarılmış kimi işarələnir. Onda deprecated: true, elan tarixi olan x-deprecation-date və əməliyyatın işləməyi dayandıra biləcəyi ən erkən tarix olan x-sunset var. Hər iki tarix RFC 3339 formatındadır.
• API dəyişiklik jurnalındakı qeyd dəyişikliyi və onun əvəzinə nədən istifadə ediləcəyini təsvir edir.
• Əməliyyatın hər cavabı aşağıdakı cədvəldəki başlıqları daşıyır.

Deprecation: @1792281600
Sunset: Sun, 18 Apr 2027 00:00:00 GMT
Link: <https://docs.cloud.example/docs/developers/rest-api/changelog/>; rel="deprecation"; type="text/html"

Bu nümunədə əməliyyat 2026-10-18 tarixində istifadədən çıxarılıb və 2027-04-18 tarixindən sonra işləməyi dayandıra bilər.

Başlıqlar əməliyyatın hər cavabında, o cümlədən 401, 403 və 429 kimi xəta cavablarında olur. İstifadədən çıxarılma barədə cavabların özündən xəbər tutmaq üçün müştəri proqramınızda Deprecation başlığını jurnala yazın və ya onun üçün xəbərdarlıq yaradın.

Sunset tarixindən sonraKeçidi kopyalayın

Sunset başlığındakı tarixə qədər istifadədən çıxarılmış əməliyyat sənədləşdirildiyi kimi işləməyə davam edir. Bu tarixdən sonra o silinə və ya dəyişdirilə bilər. Dəyişiklik jurnalındakı qeyd onun əvəzinə nədən istifadə ediləcəyini göstərir.

Siyasət necə yoxlanılırKeçidi kopyalayın

İctimai API müqaviləsindəki hər dəyişiklik ondan əvvəl dərc edilmiş müqavilə ilə avtomatik müqayisə olunur. Uyğunluğu pozan fərq dəyişikliyin buraxılmasını dayandırır. Yeganə istisna istifadədən çıxarılmış və sunset tarixi keçmiş əməliyyatdır.

Əlaqəli məzmunKeçidi kopyalayın

• API dəyişiklik jurnalı
• REST API icmalı
• Xətalar
• API istinadı