API ვერსიის სტრატეგია

რატომ გჭირდებათ ვერსია

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

ძირითადი პრინციპები

1. Additive-first: ახალი სურვილისამებრ ველები/მეთოდები/მოვლენები - დაახლ; ამოიღეთ და შეცვალეთ მნიშვნელობა - მაიორი.
2. MGC (მინიმალური საგარანტიო ხელშეკრულება) სტაბილურია; გამდიდრება - capilities/'? include = '.
3. Tolerant reader: მომხმარებლები უგულებელყოფენ უცნობ სფეროებს და სწორად განიცდიან enum- ის გაფართოებას.
4. Semantic Versioning: `MAJOR. MINOR. PATCH 'არტეფაქტებისთვის, SDK და მოვლენებისთვის.
5. Automate: schema-diff, linters და CDC ტესტები ბლოკავს breaking ცვლილებებს.

სად შეინახოთ ვერსია (მისამართის მექანიკა)

REST/HTTP

URI ვერსია: '/v1/orders 'უბრალოდ მარშრუტირება, მოსახერხებელია კარიბჭეებში. მინუსი - „დაჩრდილავს“ იდეების ევოლუციას.
მედია/სათაური: 'Accept: განაცხადი/vnd. example. orders. v1 + json '- ფორმატის ზუსტი მართვა; გაშვება უფრო რთულია.
Query ვერსია: '? ap- ვერსია = 1' - მოსახერხებელია A/B- სთვის, მაგრამ ადვილია დაკარგოთ ქეშებში/ლოგოებში.
რეკომენდაცია: URI major ხაზებისთვის + feature/capability flags და მცირე გაფართოებისთვის შინაარსის ნეგატიური.

gRPC / Protobuf

პაკეტები/სერვისები: 'პაკეტის პაკეტები. v1; მომსახურება PaymensV1; '- აშკარა ხაზები.
ჭდეების ნუმერაცია უცვლელია; დისტანციური ჭდეების გამოყენება შეუძლებელია.
ახალი ველები - 'optional'; breaking - ახალი '.v2'.

GraphQL

სქემა აშკარა მაიორების გარეშე URL- ში. ევოლუცია @ deprecated და მიგრაციის ფანჯრების საშუალებით; „ნამდვილი“ მაიორი ახალი ენდოინტის სქემაა.
აკონტროლეთ complexity/depth - ეს არის ხელშეკრულების ნაწილი.

Event-driven (Kafka/NATS/Pulsar)

ღონისძიების სახელი: 'payment. authorized. v1 '- ტიპის ვერსია.
სქემების რეესტრი (Avro/JSON Schema/Protobuf) თავსებადობის რეჟიმში (BACKWARD/FORWARD/FULL).
Major - ორმაგი-emit 'v1' და 'v2' გარდამავალი პერიოდისთვის.

ვერსიის მოდელი და ცვლილების პოლიტიკა

Semantic Versioning

MAJOR - დარღვევის ცვლილებები: ველების მოცილება/შეცვლა, კონვერტაციის გასაღებების შეცვლა, სტატუსის განსხვავებული მნიშვნელობა, ვალიდაციის გამკაცრება.
MINOR - დანამატი: ახალი არჩევითი ველები/ენდოინტები/მოვლენები, ახალი enum მნიშვნელობები tolerant-reader- ში.
PATCH - კორექტირება ხელშეკრულების და სემანტიკის შეცვლის გარეშე.

Deprecation & Sunset

მოძველებული ('Deprecated: true', '@ deprecated'), გამოაქვეყნეთ sunset თარიღი, ალტერნატივა და მიგრაციის ჰაიდი.
HTTP - სათაურები 'Sunset', 'Deprecation'; მოვლენებში - ცალკე '.deprecation. notice`.
ჩაატარეთ ტელემეტრია, რომ მიიღოთ გადაწყვეტილება მოხსნის შესახებ.

ვერსიის სტილის სტრატეგიები

REST

მთავარი ხაზები/v1 ,/v2.
MINOR: სქემების გაფართოება, '? fields =', '? include ='; უსაფრთხო enum გაფართოება.
ETag/If-Match და idempotent POST თანმიმდევრულობის გარეშე.
შეცდომები - სტაბილური ფორმატი ('ტიპი', 'code', 'trace _ id').

gRPC

დანერგეთ ახალი სერვისები/მეთოდები დარღვევებისთვის: "PaymensV2. Capture`.
შეცდომების სტატუსი და deadline სემანტიკა - ხელშეკრულების ნაწილი; ცვლილება - ახალი მეთოდი/მომსახურება.
ნაკადი: შეთანხმდით შეტყობინებების პროცედურაზე და ნუ შეცვლით მას მინორში.

GraphQL

დაამატეთ ველები და ტიპები თავისუფლად; წაშლა - '@ deprecated' + მიგრაციის ფანჯრის საშუალებით; დიდი რედიზაინი - ახალი სქემა ('/graphql-v2 ').
ინტროსპექცია და აღწერილობები - must-have მომხმარებელთა მიგრაციისთვის.

Events

Core vs enriched: ბირთვი სტაბილურია, გამდიდრება იქვე ცხოვრობს და ცალკე ვერსირებულია.
გარიგების გასაღები უცვლელია მაიორი ხაზის ფარგლებში.
მაჟორის მიგრაცია - 'dual-emit' + პროექციების/კონსიუმერების მიგრაცია.

Negotiation და კაპიტალური დროშები

Capabilities: კლიენტი აგზავნის 'X-Capabilities: risk _ score, price _ v2'; სერვერი პასუხობს გაფართოებულ წარმოდგენას.
Prefer (HTTP) და „hints“ ნაწილობრივი პასუხებისთვის.
სოკეტებში/ნაკადებში - handshake შეტყობინება მხარდაჭერილი გაფართოების ჩამონათვალით.

მაიორი ვერსიები ტკივილის გარეშე

1. RFC/ADR: რატომ გჭირდებათ მაიორი, რომელიც იშლება, რისკის მატრიცა.
2. ორმაგი-run: პარალელური გაშვება 'v1' და 'v2' (მოვლენების ორმაგი გამოქვეყნება, ორი gateway-rout, ტრეფიკის მარცვლეული).
3. მიგრაციის გადამყვანები: მარიონეტული/თარჯიმანი 'v1-v2' მძიმე მომხმარებლებისთვის.
4. Canareika: მომხმარებელთა ჯგუფების/ტოპიკის/ტესტების მიხედვით gateway.
5. Sunset გეგმა: თარიღები, კომუნიკაცია, სტენდები, ტესტის მონაცემები, გამოყენების მონიტორინგი.

პლატფორმისა და ინფრასტრუქტურის როლები

API Gateway/Service Mesh: მარშრუტი ვერსიის, სათაურების, ბილიკების მიხედვით; rate-limit и auth per-version.
Schema Registry & Catalog: ჭეშმარიტების წყარო სპეკის/სქემებისთვის დიფების ისტორიით.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: ვერსია უნდა მოხვდეს ლოგოებში/ტრეისებში/მეტრიკებში.

ვერსიის ტესტირება

Schema-diff PR- ში: დაბლოკეთ breaking.
Consumer-Driven Contracts: პროვაიდერი შემოწმებულია რეალური მომხმარებლების კონტრაქტების წინააღმდეგ.
Golden samples: საცნობარო პასუხები ვერსიაზე.
E2E კანარი: p95/p99 შედარება, შეცდომები და ტაიმაუტები ვერსიებს შორის.
მოვლენების რეპლეი: პროგნოზები გადაკეთებულია v2-ზე, შეუსაბამობის გარეშე.

მონაცემთა და ბაზების მიგრაცია

REST/gRPC- სთვის: BD მიგრაცია კოორდინირებულია ექსპანსიური და კონტრაქტით (დაამატეთ სვეტი და დაიწყეთ წერა, გადართვა და კითხვა, დაარტყა ძველი).
Events- ისთვის: ორმაგი ემიტი და კონსიუმერების მიგრაცია; ზოგჯერ - ლოგოს ხელახლა დაკვრა ახალი პროექციებისთვის.
ნუ გააკეთებთ „დიდ აფეთქებებს“ - შეწყვიტეთ ნაბიჯები უკან დახევებით.

უსაფრთხოებასთან ურთიერთობა

Scopes per ვერსია: ინდივიდუალური OIDC-scopes/როლები v1/v2.
საიდუმლოებები/ნიშნის საიდუმლოებები - ხელშეკრულების ნაწილი; მათი შეცვლა = მაიორი.
PII/PCI - არ გააფართოვოთ payload საჭიროების გარეშე; ახალი ველები - მინიმალური პრივილეგიებით.

ანტიპატერები

Swagger-wash: დაზუსტება განახლებულია, სერვერი არ არის (ან პირიქით).
Protobuf ტეგების ხელახალი გამოყენება მონაცემთა მშვიდი დაზიანებაა.
enum მნიშვნელობების შეცვლა მაიორი გარეშე.
გლობალური '/v2 '„კოსმეტიკური საშუალებების გულისთვის“: ვერსია შეფერხების გარეშე.
მათ დაივიწყეს sunset/usage მეტრიკა: შეუძლებელია ძველი ვერსიის უსაფრთხოდ ამოღება.
ერთი ზოგადი ტოპიკი სხვადასხვა მაიორისთვის: შეკვეთებისა და გასაღებების ნაზავი.

გამოქვეყნებამდე ჩეკის სია

• ცვლილებები დანამატის ან მომზადებულია ცალკეული მაიორი ხაზით.
• Linters და schema-diff მწვანე (breaking არ დაეშვა).
• განახლებულია SDK/მაგალითები/დოკუმენტაცია, თავსებადობის სქოლიოები.
• tolerant reader შედის კლიენტებში; გამოცდილი enum-fallback.
• მაიორისთვის - ორმაგი რუნის გეგმა, გადამყვანები, კანარი, sunset თარიღები და ბიულეტენები.
• მეტრიკა/ლოგები/ტრეისი შეიცავს ვერსიას და სეგმენტს.
• არსებობს სტენდი და ოქროს ნაკრები შედარებისთვის v1-v2.
• მოვლენებისთვის - სქემების რეესტრი BACKWARD/FULL რეჟიმში, განაწილების გასაღებები უცვლელია.

შაბლონების მაგალითები

REST (URI + negotiation)

მარშრუტი: '/app/v2/orders/{ id '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(ბირთვი) და' payment. enriched. v2 '(დეტალები).
გარდამავალი პერიოდისთვის მწარმოებლისგან არის 'v1' და 'v2'.

FAQ

როდის არის ნამდვილად საჭირო '/v2 '?
როდესაც ინვარიანტები/სემანტიკა იცვლება, ველები/მეთოდები ამოღებულია, იდენტიფიკატორის ფორმატი იცვლება, განაწილების გასაღები, SLA/timings ისე, რომ მომხმარებლები იშლება.

შეგიძლიათ იცხოვროთ REST- ში აშკარა ვერსიის გარეშე?
მხოლოდ მცირე სისტემებისთვის. გარე ინტეგრაციისთვის - უკეთესია აშკარა მაიორი ხაზები.

რა დროა მოძველებული ვერსიის შესანარჩუნებლად?
ეს დამოკიდებულია ეკოსისტემაზე. გარე პარტნიორებისთვის, ჩვეულებრივ, 6-12 თვეა ადრეული შეტყობინებითა და კანალიზაციით.

როგორ განსხვავდება მოვლენების ვერსია API- სგან?
მოვლენები - append-only; ახალი სემანტიკა = ახალი ტიპი '.v2' და ორმაგი ემიტი. გარიგების გასაღები ხელშეკრულების ნაწილია.

შედეგი

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