Տեխնոլոգիան և ենթակառուցվածքը բացատրում են API տարբերակումը

API տարբերակումը

1) Ինչո՞ ւ է դա անհրաժեշտ

Տարբերակումը կառավարվող միջոց է փոխելու ծառայությունների և հաճախորդների միջև պայմանագրերը առանց խափանումների։ Մեծ թվով ինտեգրիաներով (վճարումներ, KYC/AML, խաղեր, բիլինգ, հաշվետվություններ) միաժամանակ ապրում են «հին» և «նոր» հաճախորդները։ Տարբերակի ճիշտ քաղաքականությունը

նվազեցնում է թողարկման ռիսկը,

թույլ է տալիս պլանավորել բարելավումներ և անվտանգություն,

բիզնեսին տալիս է գործընկերների միգրացիայի կանխատեսելի ժամկետներ։

2) Փոփոխությունների դասակարգում

PATCH (ոչ թե կոտրող) 'առանց պայմանագրի փոփոխության (ավելացնելով արտանետվող դաշտերը, վալիդացիայի ֆիքսները)։

MINOR (ընդարձակող) 'back-compatible ընդարձակումը (նոր endpoints, դաշտեր 105)։

MAJOR (կոտրող) 'կառուցվածքի, սեմանտիկայի կամ դաշտերի/էնդպոինտների հեռացման փոփոխություն։

Խորհուրդ է տալիս SemVer 'MAJOR-ը։ MINOR. PATCH 'արտեֆակտների համար (MSK/սխեմա), մինչդեռ API-ի «արտաքին» համարը կարող է պարզեցվել (v1, v2)։

3) REST տարբերակման մոդելները

1. URI-ՈՒՄ

`GET /v1/payments/{id}`

Պլյուսներ ՝ զզվելի, քեշիրումո, հեշտ է ուղղել։ Մինուսները 'փաստաթղթերի կրկնօրինակումը, ավելի բարդ է զարգացնել։

2. Վերնագրերում (ente negotiation)

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

Պլյուսներ 'ճկունություն, «աղբի» բացակայություն URL-ում, մեդիատիպի հարմար էվոլյուցիա։ Մինուսներ 'ավելի դժվար է զննարկչի մեջ բանավեճը, անհրաժեշտ է կարգապահ հաճախորդ։

3. Կաստոմային վերնագրում

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

Պլյուսներ 'պարզապես դարպասի վրա։ Մինուսներ 'ոչ ստանդարտ, զգույշ քեշի հետ։

4. @-@ ամսաթիվը (date-based)

Լավ է fintech/հաշվետվության համար 'կանխատեսելի «կտրվածքներ» փոփոխությունների համար (օրինակ, եբեքվարտալ)։

5. Ռեսուրսի/մոդելի տարբերակումը

Առաջարկություն ՝ արտաքին ինտեգրման համար '"URI vN' + Deprecation/Sunset վերնագրեր; ներքին, դուք կարող եք «Accept» կամ տարբերակի վերնագիր, եթե դարպասը և պլատֆորմը աջակցում են դա։

4) GraphQL

Նախընտրությունը առանց գլոբալ տարբերակների։ Էվոլյուցիան դաշտերի/տեսակների ավելացման և ապակայունացման միջոցով (@ deprecated (reason: "...)։

Կոտրող փոփոխությունները միայն «մեծ» պատուհաններում (versioned schema namespace) միգրացիոն անջատողական տան հետ։

Հետևեք «n + 1» -ին և չփոխեք գոյություն ունեցող դաշտերի meaning։

5) gRPC / Protobuf

Դաշտերի համարները անփոփոխ են։ Հեռավոր դաշտերը տեղադրեք որպես «reserved»։

Ավելացրեք դաշտերը որպես optional անվտանգ պարամետրերով։

Օգտագործեք buf breaking/lint ավտոմատ ստուգման համար։

Տարբերեք փաթեթները/մոդուլները '"package payments։ v1;` → `payments. v2`.

6) Իրադարձական API (EDA)

Իրադարձության սխեման նույն պայմանագիրն է։ Պահպանեք այն Schema Registry-ում (Avro/JSON-Schema/Delobuf)։

Կոտրող փոփոխությունները իրադարձության նոր տեսակն են կամ նոր կացինը։

Տոպիկները և տարբերակները ՝ «payments»։ v1. authorized`, `payments. v2. authorized`.

Էվոլյուցիայի երաշխիքները 'backward-compatible հյուպատոսների համար LTS-ի ընթացքում։

7) Ապակայունացման քաղաքականությունը և EOL-ը

Ներդրեք թափանցիկ կանոնները

Deprecation: տեղադրված է changelog-ում և մասնագիտություններում (OpenAPI/GraphQL SYL), վերնագիրը

«Deprecation: 108» և երբ հնարավոր է «Sunset: Tue, 31 Mar 2026 00:00 GMT»։

Հաղորդակցություն ՝ email/գործընկեր պորտալ, webhooks-ծանուցումներ, rele.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-ի դեպքում տրամադրեք կրկնակի ձայնագրություն/կարդալ (dult-write/read) տվյալների սխեմաները։

9) Պայմանագիր-փորձարկումը և վերահսկումը։

OpenAPI Diff (կամ swagger-diff) - նշելով, որ MINOR/PATCH-ը չի կոտրում սխեմաները։

Spectral linting-ը ոճն է, պարտադիր մետատվյալներ (տարբերակը, Deprecation)։

Consumer-Driven Disracom (Pact) - երաշխավորում է, որ պրովայդերը չի կոտրում հաճախորդներին։

buf breaking для protobuf.

CI-ը պետք է ընկնի կոտրող փոփոխությունների ժամանակ առանց MAJOR-ի։

10) Մոսկվա և MSK K

Արտադրեք MSK-ը տարբերակներով (npm/maven/pypi) SemVer-ի և changelog-ի հետ։

Տարբերեք մեջքերը '"/docs/api/v1/openapi։ json`, `/docs/api/v2/…`.

Միջամտեք հնացած մեթոդներին MSK-ում/Deprecated-ում։

11) Observability-ը տարբերակով

Հավաքեք մետրերը առանձին

RPS/լատենտ/սխալներ տարբերակը («appi _ version» լեյբլ)։

Էնդպոինտների օգտագործման քարտեզները 'ո՞ վ է v1-ի վրա։

Ալերտներ ՝ «> 10% 4xx due to ww.ract mismatch», «հին հաճախորդները> X% T ամսաթվից հետո»։

12) Կատարումը և տարբերակները

Ճանապարհի տարբերակը բարելավում է CDN-ի հավասարակշռությունը։

Վերնագրի/մեդիատիպի տարբերակներում 'ուշադիր Vary։

`Vary: Accept, X-API-Version`.

Մի փոխեք պատասխանը MINOR-ում, որպեսզի կոտրեք քեշ-բանալիները։

13) Անվտանգություն

Մի ծածկագրեք և չփորձեք տարբերակը JWT-ում, տարբերակը որոշում է հարցումը, ոչ թե հոսքը։

Մի բացեք ներքին հավաքման համարները։ Արտաքին հաղորդագրություններում օգտագործեք «v1/v2»։

MAJOR-ի դեպքում վերանայեք validation, limits, PII դիմակավորում։

14) Մոսկվան և օգնականները

Հրապարակեք «Migration Guide v1 nov2» 'դաշտերի թեմերի աղյուսակը, հարցումների/պատասխանների օրինակները, edge-cass։

Դուք առաջարկում եք ոսպնյակներ հաճախորդների համար (CLI), որոնք լուսավորում են հնացած դաշտերը։

Մեծ գործընկերների համար 'sandbox, երկու տարբերակով և թեստային-դանասեթով։

15) Anti-patterna

«Հավիտենական v1» 'dedlines-ի բացակայությունը և օգտագործման մետրը։

Թաքնված կոտրող փոփոխությունները MINOR/PATCH-ում։

«Query string» («? v = 2») - կոտրում է քեշը և կարդալը։

«Մեկ էնդպոինտ հարյուր դրոշի արժեքներ է», դժվար է փորձարկել/փաստաթղթավորել։

16)

1. Ընտրվել է մոդել (URI/Accept/Header) արտաքին և ներքին հաճախորդների համար։

2. SemVer-ը հատուկ և SDK-ի համար, ավտոմատ breaking-71-ը CI-ում։

3. Deprecation/Sunset քաղաքականությունը և հաղորդակցման ձևանմուշները։

4. Gateway-միկրոօրգանիզացիա + kanareks, dashbords տարբերակներով։

5. CDC/Medract tes.ru կրիտիկական վճարումների համար (վճարումներ, KYC, հաշվետվություններ)։

6. Express/MSK/միգրացիոն ուղեցույցը հրապարակվում է միաժամանակ ֆորումի հետ։

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 Content 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 կոնտեքստը (պրակտիկա)

Վճարումները 'v2-ի ներդրումը նոր PBS-ի համար, որտեղ «status »/« decium _ reason» -ը ընդլայնված է։ նավի վրա mapping v1-v2 հաշվետվության համար։

KYC: MINOR ավելացնում է «pep _ screening» դաշտը, v1 հաճախորդները անտեսում են, v2-ը պահանջում է։

Պատասխանատու խաղեր/լիմիտներ: MAJOR-ը փոխում է սահմանների մոդելը (ամենօրյա/շաբաթ)։ Կրկնակի էքսպորտը զեկույցներում մինչև EOL v1։

Կարգավորողների հաշվետվությունները 'ֆիքսված տարբերակները' «reporting-2025-01»։

19) Մինի քաղաքականությունը (օրինակ wiki-ի համար)

Մոդել 'արտաքին API-ի համար' «URI/vN/»; Ներքին համար 'Accept: ... vN + json' կամ 'X-API-Version: N'։

SemVer: Հատկությունները և SDK-ը հրապարակվում են որպես 'N. minor. patch`. MAJOR-ը պահանջում է RFC/ADR։

Համատեղելիությունը ՝ MINOR/PATCH - առանց կոտրող փոփոխությունների։ Կոտրող մուտքը միայն MAJOR-ի միջոցով։

Deprecation/EOL: Գովազդը 90 օրվա ընթացքում։ Sunset-ամսաթիվը վերնագրերում։ LTS-ճյուղը կրիտիկական հաճախորդների համար։

Վերահսկողությունը 'OpenAPI diff/buf breaking CI, CDC հիմնական ինտեգրման համար։

Observability: metrics/logs '«api _ version» պիտակով։

Ալգորիթմներ ՝ canary 5 տոկոսը 210 ժամ, ապա ՝ մինչև 100 տոկոսը կանաչ մետրիներում։

Արդյունքը

Տարբերակումը ոչ թե URL-ում «/v2 »-ի մասին է, այլ գործընթացի մասին 'էվոլյուցիայի ակնհայտ կանոնները, կոդավորման ավտոմատ ստուգումները, կառավարվող օրինագծերը և հարգանքը ինտեգրման նկատմամբ։ Մուտքագրեք հասկանալի քաղաքականություն, ավտոմատիզացրեք վերահսկողությունը և դիտարկումը, և փոփոխությունները կդադարեն սպառնալ ապրանքին։