API dəyişiklik jurnalı
İctimai REST API-dəki tarixli dəyişikliklər, ən yenisi birinci; API versiyası, dəyişiklik növü, təsirlənən əməliyyatlar və sunset tarixləri.
Bu dəyişiklik jurnalı ictimai REST API-dəki dəyişiklikləri ən yenisi birinci olmaqla sadalayır. Hər qeyd tarixini, API versiyasını və müqavilə versiyasını, dəyişikliyin növünü və təsir etdiyi əməliyyatları göstərir. Müqavilə versiyası https://<api-host>/openapi.json ünvanındakı OpenAPI sənədinin info.version dəyəridir.
Uyğunluğu pozan dəyişiklik qüvvəyə minməzdən ən azı 6 ay əvvəl burada elan edilir. Qaydalar üçün API versiyalaşdırması və istifadədən çıxarılma səhifəsinə baxın.
| Növ | Mənası |
|---|---|
| Əlavə edilib | Yeni əməliyyat, sahə, başlıq və ya funksiya. Geriyə uyğundur. |
| Dəyişdirilib | Dəyişmiş davranış. Ümumi istifadəyə verilməzdən əvvəl belə dəyişiklik uyğunluğu poza bilərdi. |
| İstifadədən çıxarılıb | Əməliyyat sunset tarixinə qədər işləməyə davam edir, ondan sonra isə silinə və ya dəyişdirilə bilər. |
| Silinib | Əməliyyat və ya sahə sunset tarixindən sonra silinib. |
| Təhlükəsizlik | Təhlükəsizlik boşluğunu bağlayan dəyişiklik. |
2026-10-18
API versiyası v1, müqavilə versiyası 1.4.0.
İstifadədən çıxarılıb
Bu əməliyyatlar istifadədən çıxarılıb. Sunset: 2027-04-18. Onların cavabları Deprecation, Sunset və Link başlıqlarını daşıyır.
Əlavə edilib
- API-nin versiyalaşdırma və istifadədən çıxarılma siyasəti.
- İstifadədən çıxarılmış əməliyyatın hər cavabında
Deprecation,SunsetvəLinkbaşlıqları, OpenAPI sənədində isə istifadədən çıxarılmış əməliyyatlardax-deprecation-datevəx-sunsetsahələri.
Ümumi istifadəyə verilməzdən əvvəlki dəyişikliklər
Bu dəyişikliklər ümumi istifadəyə verilməzdən əvvəl edilib, ona görə də bildiriş müddətinə tabe deyildi. Onlar API versiyası v1 üçün keçərlidir.
| Tarix | Növ | Dəyişiklik |
|---|---|---|
| 2026-10-19 | Dəyişdirilib | API tokeni və ya xidmət hesabı açarı ilə Idempotency-Key başlığı yalnız resurs yaradan və 202 Accepted cavabı verən POST sorğularında məcburidir. DELETE, PATCH və PUT sorğuları, həmçinin mövcud resurslar üzərində əməliyyatlar yenidən açarsız qəbul edilir. Bu sorğularla açar göndərdikdə açardan istifadə edən əməliyyatlarda eyni açarla təkrar cəhd yenə ilk cavabı qaytarır. API arayışı açarı nəzərə almayan əməliyyatlarda Idempotency-Key başlığını artıq göstərmir. |
| 2026-10-19 | Təhlükəsizlik | Uyğunluğu pozan dəyişiklik. API tokeni ilə abunəlik yaratmaq (POST /tenants/{tenantId}/subscriptions) iam:write ilə yanaşı billing:write miqyası da tələb edir. Bu miqyas olmadan sorğu TOKEN_SCOPE_MISSING səbəbi ilə 403 Forbidden qaytarır. Xidmət hesabı açarları rədd edilməyə davam edir. |
| 2026-10-18 | Təhlükəsizlik | Xidmət hesabı (service account) açarlarının miqyasları (scope) var və onlar API tokenləri (API token) ilə eyni miqyas yoxlamasından keçir. Miqyassız yaradılan açar iam:write istisna olmaqla bütün miqyasları alır. Açarın iam:write miqyası ola bilməz: belə sorğu 422 Unprocessable Entity qaytarır. /tenants/ altındakı yazma sorğuları da daxil olmaqla iam:write tələb edən əməliyyatlar xidmət hesabı açarlarını INTERACTIVE_SESSION_REQUIRED kodu ilə 403 Forbidden cavabı ilə rədd edir. |
| 2026-10-18 | Əlavə edilib | API hostu https://<api-host>/docs ünvanında interaktiv API bələdçisini, https://<api-host>/openapi.json ünvanında isə OpenAPI sənədini təqdim edir. |
| 2026-10-18 | Dəyişdirilib | Bütün elementləri qaytaran siyahı əməliyyatları indi page və pageSize qəbul edir. pageSize 1–200 aralığındadır, standart dəyəri 200-dür. Daha böyük dəyər 422 Unprocessable Entity qaytarır. |
| 2026-10-18 | Dəyişdirilib | OpenAPI sənədinin serveri API hostundakı /api/v1 yoludur. Dərc edilən API istinadı API müqaviləsindən ictimai olmayan əməliyyatları kənarda qoyan qayda ilə yaradılır. |
| 2026-10-18 | Dəyişdirilib | API tokeni və ya xidmət hesabı açarı ilə göndərilən yazma sorğusu, əməliyyat bu başlığı qəbul edirsə, Idempotency-Key başlığını daşımalıdır. Onsuz sorğu IDEMPOTENCY_KEY_REQUIRED kodu ilə 400 Bad Request qaytarır. Açarlar hər tenant üçün ayrıca saxlanılır, ona görə də iki tenant-dakı eyni açar iki fərqli sorğunu müəyyən edir. |
| 2026-10-18 | Dəyişdirilib | API tokeni və ya xidmət hesabı açarı ilə göndərilən sorğular hər giriş məlumatı və hər tenant üzrə məhdudlaşdırılır. Onların cavabları X-RateLimit-Limit, X-RateLimit-Remaining və X-RateLimit-Reset başlıqlarını daşıyır. Limiti aşan sorğu RATE_LIMITED kodu və Retry-After başlığı ilə 429 Too Many Requests qaytarır. |
| 2026-10-18 | Dəyişdirilib | Token miqyasları kataloqunda 17 miqyas var ki, API-nin hər sahəsinə açıq miqyasla müraciət etmək mümkün olsun. OpenAPI sənədi hər əməliyyatın tələb etdiyi miqyasları x-required-scopes daxilində sadalayır. Activity Log iam:read və ya audit:read qəbul edir. Token özündə olmayan miqyasla token və ya açar yarada bilməz: details.reason dəyəri TOKEN_SCOPE_MISSING olan 403 Forbidden. Token həmçinin özündən gec bitən və ya IP icazə siyahısı öz siyahısının daxilində olmayan token yarada bilməz: details.reason dəyəri TOKEN_FENCE_EXCEEDED olan 403 Forbidden. |
| 2026-10-17 | Təhlükəsizlik | Xidmət hesabını deaktiv etmək və ya silmək onun açarlarını və yaratdığı API tokenlərini ləğv edir. Hesabı yenidən aktiv etmək onları bərpa etmir. API tokeninin xüsusi bitmə tarixi ən çoxu 365 gün sonra ola bilər; daha gec tarix details.reason dəyəri token_lifetime_exceeds_maximum olan 422 Unprocessable Entity qaytarır. |
| 2026-10-17 | Əlavə edilib | Activity Log hadisələri çağıranın autentifikasiyadan necə keçdiyini göstərən actorType sahəsini daşıyır: user, api_token, service_account_key və ya system. Onlar həmçinin çağırışı edən API tokeninin və ya xidmət hesabı açarının ictimai ID-si olan credentialId sahəsini daşıyır. |