API თავსებადობა და განახლებები

1) თავსებადობის ძირითადი პრინციპები

Additive-first: დაამატეთ ახალი, ძველი დაშლის გარეშე (ახალი სურვილისამებრ ველები/endpoints, ახალი enum მნიშვნელობები).
სტაბილური კონტრაქტები: „რაც დაპირებულია სპეციფიკაციაში - ის მუშაობს“; ქცევა დოკუმენტირებულია.
Backward> Forward: საპირისპირო თავსებადობის პრიორიტეტი; forward ნებადართულია tolerant readers- ის საშუალებით.
დოკუმენტები პირველია: ჭეშმარიტების ერთადერთი წყარო არის სქემის ვერსია რეგისტრის (OpenAPI/AsyncAPI/Proto).
აშკარა ევოლუცია: breaking - მხოლოდ ახალი მაიორი ვერსიისა და მიგრაციის სახელმძღვანელოს საშუალებით.

2) ცვლილებების ტაქსონომია

2. 1 თავსებადი (MINOR/PATCH)

სურვილისამებრ ველების/cheders, ახალი endpoints, query პარამეტრების დამატება ნაგულისხმევებით.
ლიმიტების ზრდა ('page _ size', TTL), შეცდომების დაზუსტება კოდების/სემანტიკის შეცვლის გარეშე.
enum მნიშვნელობების დამატება, თუ მომხმარებლები უგულებელყოფენ „უცნობ“ (tolerant-reader).

2. 2 ორაზროვანი (Behavioral)

ნაგულისხმევი ცვლილებები, დალაგების პროცედურა, თხელი ტაიმაუტები, კვოტები - შეიძლება „დაირღვეს“ ბიზნეს ლოგიკა. მოითხოვს RFC + ანონსი და კანარი.

2. 3 გატეხილი (MAJOR)

ველების შეცვლა/მოცილება, ტიპის/ფორმატის შეცვლა, შეცდომების კოდების შეცვლა, კონტრაქტების/ავტორიზაციის სქემების საპირისპირო შეუთავსებლობა.

3) ვერსიის პოლიტიკა

სტრატეგია: 'path versioning' ('/v1 ', '/v2').
მცირე/პატჩი: „დაამატეთ, ნუ გატეხთ“.
დათარიღებული სათაურები (დამატებითი): 'X-API-ვერსია-თარიღი' რბილი თანდათანობითი ცვლილებებისთვის.
მედია ტიპები (ოპერა) : `Accept: application/vnd. acme. v1 + json 'თხელი გრანულირებისთვის.

4) დეპრესიები და სუნსეტი

4. 1 საკომუნიკაციო სათაურები


Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2 დასკვნის პროცედურა

1. განცხადება პორტალზე/შეტყობინებაში/SDK release notes.
2. გამაფრთხილებელი ფანჯარა 90-180 დღე.
3. დაშბორდის სტატუსები.
4. Sunset- ის შემდეგ - 410 Gone ან „read-only“ რეჟიმი გრეის პერიოდისთვის, თუ შეთანხმებულია.

5) მიგრაცია და ვერსიების ერთობლივი თანაცხოვრება

ორმაგი write/dual-read გარდამავალ პერიოდში და ანგარიშების შერიგება.
გადამყვანები (დროებითი): ძველი payload gateway გარდაქმნა - ახალი სქემები; ადაპტერის სიცოცხლის ხანგრძლივობა შეზღუდულია.
SDK დახმარება: გამოშვებები, რომლებიც მხარს უჭერენ ორივე ვერსიას, დეპრესიის გაფრთხილებებით (1 ჯერ თითო პროცესზე).
Fich დროშები: ახალი სემანტიკის ჩართვა გასაღებების/ტენანტების ჩამონათვალის მიხედვით.

6) Backward და forward თავსებადობა

6. 1 Backward (ძველი მომხმარებლები - ახალი სერვერი)

არ შეცვალოთ ფორმატები/სავალდებულო.
ახალი ველები მხოლოდ არჩევითია.
შეცდომები - წინა 'error _ code ", დაამატეთ ახალი კოდები, არ შეცვალოთ.

6. 2 ფორვარდი (ახალი მომხმარებლები - ძველი სერვერი)

შეამოწმეთ შესაძლებლობების არსებობა 'OPTIONS '/'/ვერსიების "საშუალებით.
გრეის ქცევა: კლიენტმა უნდა მოითმინოს დაკარგული იხვები.

7) კონტრაქტები და ავტომატური შემოწმებები

რეგისტრი: შეინახეთ სქემების ვერსიები; PR დიფები - მოხსენებები „breaking/non-breaking“.
ლინტერი: სახელები/ტიპები, იდემპოტენტობა, პაგინაცია, სტაბილური კოდები.
CDC (Consumer-Driven Contracts): ინტეგრატორების ტესტები CI მიმწოდებელში (Pact და ანალოგები).
კარიბჭე: PR ბლოკირებულია breaking 'major bump '/RFC- ის გარეშე.

CI ნაბიჯის მაგალითი:

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) კანარის გამოშვება და უკან დაბრუნება

Canary გამოტოვება SLO გაუარესების დროს (5xx/latency/429).
ბეტა გასაღებები: allowlist- ის ახალი ვერსიების წვდომა.
Release freeze: error-budget- ის დაწვის დროს.
მიღების ანალიტიკა: ტრეფიკის/მომხმარებლების წილი ახალ ვერსიაზე, მიგრაციის დრო.

9) თავსებადობა დეტალებში: შეცდომები, პაგინაცია, იდემპოტენტობა

9. 1 შეცდომები

არ შეცვალოთ HTTP სტატუსები არსებულ სცენარებში.
'error _ code' - სტაბილური; ახალი კოდების დამატება მხოლოდ.
'განაცხადი/problem + json' - ერთი ფორმატი.

9. 2 პაგინაცია

გადასვლა cursor/keyset = MINOR, თუ ძველი 'offset/limit' მხარს უჭერს.
აღწერეთ დახარისხება '(განახლება _ at, id)' და კურსორის სტაბილურობა.

9. 3 Idempotency

Write- ისთვის - 'Idempotency-Key' + '409 IDEMP _ REPLAY' კონფლიქტის დროს.
მიგრაციამ არ უნდა შეცვალოს იდემპოტენტურობის სემანტიკა.

10) Gateway ტრანსფორმაცია (როდესაც შესაფერისია)

Map v1 - v2 ველები, შეცდომების ნორმალიზება, თარიღების/ფულის ფორმატის გარდაქმნა.
Guardrails: ტრანსფორმაციები გამჭვირვალე და ლოგიკურია; ნუ დაიმალებით breaking, მაგრამ გამოიყენეთ როგორც ხიდი შეზღუდული ვადით.

11) კომუნიკაციები და პორტალი

Changelog с датами (`added/changed/deprecated/removed/fixed`).
ვერსიის ბარათი: სტატუსი (beta/GA/deprecated), sunset თარიღი, ბმულები ჰაიდებზე.
შეტყობინებების ვებსაიტები: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + ბანერი პორტალში.

12) წარმატების მეტრიკა

Adoption rate v2 (მოთხოვნით/მომხმარებლებისთვის).
Backward-compat incidents (col-vo „გატეხილი“).
Error mix (აქციები 4xx/5xx/429) გამოშვების შემდეგ.
Time-to-Adopt საშუალო.
მხარდაჭერა load (თიკეტები/კვირა).
Cost-to-Serve (ზარის ინფრასტრუქტურული ღირებულება).

13) შაბლონები და მაგალითები

13. 1 ვერსიები და დეპრესიები


X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 ვერსიის პოლიტიკა (YAML ფრაგმენტი)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 OpenAPI: ველის თავსებადი დამატება

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) გამოშვების ჩეკის სია (MINOR/MAJOR)

MINOR

DIFF: non-breaking, linter მწვანე
დოკუმენტაცია/SDK განახლებულია (მაგალითები/კოდეკები)
Canareika + მანქანა SLO
კომის გეგმა, გვერდი პორტალში
დაშბორდები adoption და შეცდომები

MAJOR

RFC/ADR, sunset თარიღი და ფანჯარა 90-180 დღის განმავლობაში
v1-v2 ხიდი (gateway) და მიგრაციის სახელმძღვანელო
ორმაგი write/read და crypts
SDK ორივე API + გაფრთხილებით
მფრინავი ძირითადი ინტეგრატორებით

15) განხორციელების გეგმა (3 გამეორება)

1. საძირკველი (2 კვირა):

Registry სქემები, ლინტი და auto-diff CI- ში; თავსებადობის პოლიტიკა; სათაურები 'Deprecation/Sunset'.

2. სახელმძღვანელო გამოშვებები (3-4 კვირა):

კანარიკი, ფიგურის დროშები, SLO ალერტები; ვერსიის პორტალი; SDK გამოშვებები 2 ფილიალის მხარდაჭერით.

3. ავტომატიზაცია და მასშტაბები (მუდმივად):

CDC მომხმარებელთა ტესტები CI- ში, სუნსეტის პროგნოზი adoption ტენდენციების, ავტომატური ნოტიფიკაციებისა და შეხსენებების შესახებ.

16) მინი-FAQ

შესაძლებელია თუ არა ველის ტიპის შეცვლა მაიორი გარეშე?
არა. „სტრიქონიც“ კი არის breaking. შეიყვანეთ ახალი ველი, ძველი - დეპრესია.

Enum: შეგიძლიათ დაამატოთ მნიშვნელობები?
დიახ, თუ მომხმარებლები ტოლერანტული მიმდევრები არიან. წინააღმდეგ შემთხვევაში - პირველი შეტყობინება და ბეტა.

რამდენი ძველი ვერსიის შესანარჩუნებლად?
ჯერჯერობით, ახალი გამოცემა 95% -ს შეადგენს და დეპრესიის ფანჯარა შენარჩუნებულია. შეადგინეთ ვადა პოლიტიკაში.

შედეგი

API- ს თავსებადობა არის დისციპლინა: additive მიდგომა, ოფიციალური სქემები და დიფები, კანარის გამოშვებები, მკაფიო დეპრესიები და კონტროლირებადი მიგრაცია. გააძლიერეთ ცვლილებების პოლიტიკა, ავტომატიზირებული შემოწმებები და კომუნიკაციები, გაზომეთ adoption - და თქვენი განახლებები შეწყვეტს მომხმარებლების დაშლას, ხოლო ევოლუციის სიჩქარე გაიზრდება საიმედოობის დაკარგვის გარეშე.

API თავსებადობა და განახლებები

MAJOR

შედეგი

დაგვიკავშირდით

სწრაფი კავშირი

ვიდეო მალე განახლდება

ჩვენ ახლა ძალიან დაკავებული ვართ პროექტებით