ტექნოლოგია და ინფრასტრუქტურა - API ვერსია

ვერსია API

1) რატომ არის ეს აუცილებელი?

ვერსია არის კონტროლირებადი გზა სერვისებსა და მომხმარებლებს შორის ხელშეკრულებების შეცვლის გარეშე. დიდი რაოდენობით ინტეგრაციის მქონე პროდუქტებში (გადახდები, KYC/AML, თამაშები, ბილინგი, ანგარიშგებები), „ძველი“ და „ახალი“ მომხმარებლები ერთდროულად ცხოვრობენ. სწორი ვერსიის პოლიტიკა:

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

2) ცვლილებების კლასიფიკაცია

PATCH (არ დაარღვიოს): კორექტირება ხელშეკრულების შეცვლის გარეშე (არჩევითი ველების დამატება, ვალიდაციის ფიქსაცია).
MINOR (გაფართოება): უკუკავშირის გაფართოება (ახალი endpoints, ველები default- ით).
MAJOR (დარღვევა): სტრუქტურის ცვლილება, სემანტიკა ან ველების/ენდოინების მოცილება.

რეკომენდებულია SemVer 'MAJOR. MINOR. PATCH 'არტეფაქტებისთვის (SDK/სქემები), ხოლო „გარე“ API ნომერი შეიძლება გამარტივდეს (v1, v2).

3) REST ვერსიის მოდელები

1. URI- ში:

`GET /v1/payments/{id}`

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

2. სათაურებში (შინაარსი negotiation):

`Accept: application/vnd. company. payments. v2+json`

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

3. კასტომის სათაურში:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

დადებითი: უბრალოდ კარიბჭეზე. უარყოფითი: სტანდარტი არ არსებობს, ფრთხილად ქეში.

4. თარიღი ვერსია:

კარგია fintech/ანგარიშგებისთვის: პროგნოზირებადი „ჭრილობები“ ცვლილებები (მაგალითად, კვარტალური).

5. რესურსის/მოდელის ვერსია:

იმავე ენდოინტს შეუძლია სხვადასხვა სპექტაკლის დაბრუნება: 'fields =...' ან 'profile = lite	full`. ეს არის დამატება, არა ვერსიის შეცვლა.

რეკომენდაცია: გარე ინტეგრაციისთვის - 'URI vN' + Deprecation/Sunset სათაურები; შიდა - თქვენ შეგიძლიათ 'Accept' ან ვერსიის სათაური, თუ კარიბჭე და პლატფორმა მხარს უჭერს მას.

4) GraphQL

უპირატესობა - გლობალური ვერსიების გარეშე. ევოლუცია ველების/ტიპების დამატებით და განაწილებით ('@ deprecated (reason: „“...)').
გაფუჭებული ცვლილებები - მხოლოდ „დიდ“ ფანჯრებში (მიგრაციის ჰაიდთან ერთად).
დაიცავით „n + 1“ და არ შეცვალოთ არსებული ველები.

5) gRPC / Protobuf

მინდვრის ნომრები უცვლელია. დისტანციური ველები აღნიშნეთ, როგორც „აღდგენა“.
დაამატეთ ველები, როგორც უსაფრთხო default.
გამოიყენეთ breaking/lint თავსებადობის ავტომატური შესამოწმებლად.
შეცვალეთ პაკეტები/მოდულები: 'პაკეტის პაკეტები. v1;` → `payments. v2`.

6) ღონისძიების API (EDA)

ღონისძიების სქემა იგივე კონტრაქტია. შეინახეთ იგი Schema Registry- ში (Avro/JSON-Schema/Protobuf).
ტოპიკა და ვერსიები: 'payments. v1. authorized`, `payments. v2. authorized`.
გატეხილი ცვლილებები - ღონისძიების ახალი ტიპი ან ახალი ტოპიკი.
ევოლუციის გარანტიები: backward compatible საკონსულოებისთვის LTS პერიოდის განმავლობაში.

7) განაწილების პოლიტიკა და EOL

შემოიღეთ გამჭვირვალე წესები:

Deprecation: ეტიკეტები changelog და სპეციფიკაციებში (OpenAPI/GraphQL SDL), სათაური
'დეპრესია: ნამდვილი' და როდის არის შესაძლებელი 'Sunset: Tue, 31 Mar 2026 00:00 GMT'.
კომუნიკაციები: პარტნიორის email/პორტალი, webhooks შეტყობინებები, release notes.
ვადები: MINOR - 3-6 თვის მხარდაჭერა, MAJOR - 9-18 თვე (ეს დამოკიდებულია კრიტიკაზე).
დროებითი ფანჯრები: ჩაწერეთ API ვერსიის პოლიტიკაში.

8) მარშრუტიზაცია და გამოშვებები

API Gateway (Kong/Apigee/Nginx/Envoy): წესები პრეფიქსი '/v1/', სათაურით ან მედიატიპით.

მარშრუტის მაგალითი:


if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: შეადარეთ ახალი ვერსია ტრაფიკის 1-5% -ით, შეადარეთ მეტრიკა და ხელშეკრულების შეცდომების ლოგოები.
Feature Flags: ჩვენ ვმალავთ ქცევას ხელშეკრულების შეცვლის გარეშე.
Zero-downtime მიგრაცია: MAJOR- ში უზრუნველყეთ მონაცემთა სქემის ორმაგი ჩაწერა/კითხვა.

9) კონტრაქტის ტესტირება და თავსებადობის კონტროლი

OpenAPI Diff (ან swagger-diff) - შეამოწმეთ, რომ MINOR/PATCH არ არღვევს სქემებს.
სპექტრული ლინტინგი - სავალდებულო მეტამონაცემები (ვერსია, დეპრესია).
Consumer-Driven Contracts (Pact) - უზრუნველყოფს, რომ პროვაიდერი არ არღვევს მომხმარებელს.
buf breaking для protobuf.
CI უნდა დაეცეს გატეხილი ცვლილებებით MAJOR- ის გაზრდის გარეშე.

10) დოკუმენტაცია და SDK

სპეკების ვერსია: '/docs/aps/v1/openapi. json`, `/docs/api/v2/…`.
წარმოქმნის SDK ვერსიების მიხედვით (npm/maven/pypi) SemVer და changelog.
შეცვალეთ მოძველებული მეთოდები SDK პრეზენტაციებში/Deprecated.

11) Observability ვერსიით

ცალკე შეაგროვეთ მეტრიკები:

RPS/ლატენტობა/შეცდომები ვერსიაზე ('app_ ვერსია' ეტიკეტი).
ენდოინების გამოყენების ბარათები: ვინ არის სხვა v1?
ალერტები: „> 10% 4xx due to contract mismatch“, „ძველი მომხმარებლები> X% T- თარიღის შემდეგ“.

12) კეშირება და ვერსიები

გზის ვერსია აუმჯობესებს CDN ქეშირებას.

სათაურით/მედია ვერსიებით - Vary- ს ყურადღებით:

`Vary: Accept, X-API-Version`.
ნუ შეცვლით პასუხის სემანტიკას MINOR- ში ისე, რომ დაარღვიოთ ქეშის გასაღებები.

13) უსაფრთხოება

არ დაშიფროთ და არ დააკავშიროთ ვერსია JWT- ში - ვერსია განსაზღვრავს მოთხოვნას და არა ნიშანს.
ნუ გამოავლენთ შიდა შეკრების ნომრებს. გარე შეტყობინებებში გამოიყენეთ „v1/v2“.
MAJOR- ის ქვეშ გადახედეთ ვალიდაციას, ლიმიტებს, შენიღბვას PII.

14) მიგრაცია და მანქანის თანაშემწეები

გამოაქვეყნეთ „Migration Guide v1-v2“: ველების შესაბამისობის ცხრილი, მოთხოვნის/პასუხების მაგალითები, edge შემთხვევები.
გთავაზობთ ლინზებს მომხმარებლებისთვის (CLI), რომლებიც ანათებენ მოძველებულ ველებს.
მსხვილი პარტნიორებისთვის - sandbox ორი ვერსიით და ტესტის თარიღი.

15) ანტი შაბლონები

„მარადიული v1“: ვადების არარსებობა და გამოყენების მეტრიკა.
ფარული დარღვევის ცვლილებები MINOR/PATCH.
„ვერსია query string“ ('? v = 2') - არღვევს ქეში და კითხულობს.
„ერთი ენდოინტი - დროშის ასი მნიშვნელობა“: ძნელია ტესტირება/დოკუმენტაცია.

16) განხორციელების შემოწმების სია

1. შეირჩა მოდელი (URI/Accept/Header) გარე და შიდა მომხმარებლებისთვის.
2. SemVer სპეციფიკაციებისთვის და SDK, ავტომატური შემოწმება CI- ში.
3. დეპრესია/Sunset პოლიტიკა და კომუნიკაციის შაბლონები.
4. Gateway მარშრუტიზაცია + კანარი, დაშბორდები ვერსიით.
5. CDC/Contract tests კრიტიკულ ინტეგრაციისთვის (გადახდები, KYC, ანგარიშები).
6. დოკუმენტაცია/SDK/მიგრაციის სახელმძღვანელო ქვეყნდება გამოშვების პარალელურად.
7. EOL გეგმა თარიღებითა და პასუხისმგებლობით.

17) მაგალითები

17. 1 REST (URI + სათაურები)

მოთხოვნა:


GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

პასუხი:

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

განაწილების სათაურები (v1):


Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 შინაარსი Negotiation (მედია)


GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (ველის გაუქმება)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 მოვლენის მოდელი

ტოპიკები:

`wallet. v1. balance. updated`
`wallet. v2. balance. changed '(ახალი მოვლენა გაფართოებული სქემით)

სქემები ინახება Registry- ში, პროდიუსერი არ აქვეყნებს მოვლენებს სქემით, რომელიც არღვევს თავსებადობას.

18) iGaming/fintech კონტექსტი (პრაქტიკა)

გადახდები: ახალი PSP- ის v2 შეყვანა, სადაც გაფართოვდა 'status '/' decline _ reason'; Mapping v1-v2 კარიბჭეზე ანგარიშგების მიზნით.
KYC: MINOR უმატებს ველს 'pep _ screening ", მომხმარებლები v1 უგულებელყოფენ, v2 მოითხოვს.
საპასუხისმგებლო თამაშები/ლიმიტები: MAJOR ცვლის ლიმიტების მოდელს (ყოველდღიური/ყოველკვირეული). ორმაგი ექსპორტი EOL v1- მდე.
რეგულატორებისთვის მოხსენებები: ფიქსირებული თარიღის ვერსიები: 'reporting-2025-01'.

19) მინი პოლიტიკა (მაგალითი ვიკისთვის)

მოდელი: გარე API- სთვის - 'URI/vN/'; შიდა - 'Accept:... vN + json' ან 'X-API-Version: N'.
SemVer: სპეციფიკაციები და SDK ქვეყნდება, როგორც 'N. minor. patch`. MAJOR მოითხოვს RFC/ADR.
თავსებადობა: MINOR/PATCH - დარღვევის გარეშე. დაშლა მხოლოდ MAJOR- ის საშუალებით.
დეპრესია/EOL: განცხადება 90 დღის განმავლობაში; Sunset თარიღი სათაურებში; LTS ფილიალი კრიტიკული მომხმარებლებისთვის.
კონტროლი: OpenAPI diff/buf breaking CI, CDC ძირითადი ინტეგრაციისთვის.
Observability: მეტრიკა/ლოგოები ეტიკეტით 'app_ version ".
გამოშვებები: კანარი 5% -24h, შემდეგ ეტაპობრივად 100% -მდე მწვანე მეტრებში.

შედეგი

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

ტექნოლოგია და ინფრასტრუქტურა - API ვერსია

შედეგი

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

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

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

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