API տարբերակման ռազմավարությունը

Ինչու՞ պետք է տարբերակել

API-ն ավելի արագ է փոխվում, քան հաճախորդները։ Տարբերակումը թույլ է տալիս թողարկել ֆիչեր և կառավարել սխալները առանց ինտեգրման, տալիս է փոփոխությունների ծեսը և կանխատեսելի դարձնել էվոլյուցիան։ Բանալին այն է, որ լռելյայն, majors-ը միայն կոտրվածքների, ավտոմատ ստուգումների և մտածված sunset քաղաքականության համար է։

Հիմնական սկզբունքները

1. Meditive-first: Նոր oporative դաշտեր/մեթոդներ/իրադարձություններ - ok; Իմաստի փոփոխությունը մաժոր է։

2. MGC (նվազագույն երաշխիքային պայմանագիր) ռոտիլեն; հարստացումը 'capabilities/', include ='։

3. Toler.rader: հաճախորդները անտեսում են անհայտ դաշտերը և ճիշտ անհանգստացնում են enum-ի ընդլայնումը։

4. Semantic Versioning: `MAJOR. MINOR. PATCH 'արտեֆակտների, MSK-ի և իրադարձությունների համար։

5. Automate: schema-diff, ոսպնյակներ և CDC թեստերը արգելափակում են breaking-փոփոխությունները։

Որտեղ պահել տարբերակը (հասցեագրման մեխանիկա)

REST/HTTP

URI տարբերակը '«/v1/orders »-ը պարզապես անցնում է, հարմար է դռների մեջ։ Մինուսը «փակցնում» է ներկայացումների էվոլյուցիան։

Մեդիատիպ/վերնագիր ՝ "Accept: Accept: Acplance/vnd. example. orders. v1 + json "- ճշգրիտ կառավարումը ֆորմատով; ավելի դժվար է բանավեճել։

Query տարբերակը '«? Api-version = 1» -ը հարմար է A/B-ի համար, բայց հեշտ է կորցնել կեշերի/լոգարանների մեջ։

Առաջարկություն: URI-ը major գծերի համար + feature/capability flags-ի և minore-ի տարածման համար։

gRPC / Protobuf

Փաթեթներ/ծառայություններ ՝ «package payments»։ v1; Paymox V1; "- ակնհայտ գծեր։

Համարակալումը անփոփոխ է. հեռավոր թեստեր չօգտագործել։

Նոր դաշտերը '«optional»; breaking-ը նոր «.v2» է։

GraphQL

Սխեմա առանց ակնհայտ major URL-ում։ Էվոլյուցիան @ deprecated և պատուհանի միջոցով։ «իրական» major-ը նոր էնդպոինտ սխեմա է։

Վերահսկեք complexity/depth-ը պայմանագրի մի մասն է։

Event-driven (Kafka/NATS/Pulsar)

Իրադարձության անունը '

Ստանդարտ սխեմաները (Avro/JSON Schema/Eurobuf) կոդավորման ռեժիմներով (BACKWARD/FORWARD/FOX)։

Major emit-emit 'v1 "և" v2 "անցումային ժամանակահատվածի համար։

Տարբերակների և քաղաքականության մոդելը

Semantic Versioning

MAJOR-ը կոտրող փոփոխություններ է 'դաշտերի հեռացում/վերանվանումը, անջատման փոփոխությունը, ստատուսի այլ իմաստը, վալիդացիայի խստացումը։

MINOR-ը ադիդիտիվ դաշտեր է 'նոր ալգորիթմային դաշտեր/endpoints/իրադարձություններ, նոր enum արժեքներ toler.ru-reader-ում։

PATCH - առանց պայմանագրի և սեմանտիկայի փոփոխության։

Deprecation & Sunset

Պոմպեցեք հնացած ("Deprecated: www.d. '," @ deprecated "), հրապարակեք sunset-ամսաթիվը, այլընտրանքը և www.d-ը։

HTTP-ում '«Sunset», «Deprecation» վերնագրերը։ իրադարձություններում 'առանձին' .deprec.ru։ notice`.

Հեռաչափություն տվեք usage-ին, որպեսզի որոշեք հեռացնել։

Տարբերակիչ ռազմավարություններ ստիլների վրա

REST

Major-գծերը/v1 ,/v2։

MINOR 'սխեմաների ընդլայնումը, «fields =», «? include =»; անվտանգ enum-ընդլայնումներ։

ETag/If-Match և imempotent POST-ի համար առանց կոտրվածքների։

Սխալները կայուն ձևաչափ են («type», «code», «trace _ id»)։

gRPC

Ներկայացրեք նոր ծառայություններ/ստուգման մեթոդներ '"Paymase V2։ Capture`.

Սխալների ստատուսները և deadom սեմանտիկան պայմանագրի մի մասն են։ փոփոխությունը կատարվում է նոր մեթոդ/ծառայություն։

Սթրիմինգ 'համաձայնեք հաղորդագրությունների կարգի մասին և մի փոխեք այն minor-ում։

GraphQL

Ավելացրեք դաշտերը և տեսակները ազատ։ 24- «@ deprecated» + պատուհանի միջոցով։ մեծ ռեդիզինը նոր սխեմա է («/graphql-v2 »)։

International-ը և նկարագրությունը must-have հաճախորդների խմբակցությունների համար։

Events

Divs enriched: միջուկը կայուն է, հարստացումը ապրում է մոտակայքում և տարբերակվում է առանձին։

Կուսակցության բանալին անփոփոխ է major-գծի սահմաններում։

Major-2019-ը '«dom-emit» + պրոյեկտների/կոնսուումերների խմբակցությունն է։

Negotiation և capability դրոշները

Capabilities: Հաճախորդը ուղարկում է «X-Capabilities: risk _ score, price _ v2»; սերվերը համապատասխանում է ընդլայնված ներկայացմանը։

Դելֆերը (HTTP) և «hinae» մասնակի պատասխանների համար։

Գանձերում/strimes - handshake հաղորդագրությունը աջակցվող ընդարձակումների ցուցակով։

Major տարբերակը առանց ցավի

1. RSA/ADR: Ինչու՞ է անհրաժեշտ major, որը կոտրվում է, ռիսկերի մատրիցը։

2. Dance-run: զուգահեռ գործարկումը 'v1' և 'v2 "(իրադարձությունների կրկնակի հրատարակումը, երկու gateway-rout, հացահատիկ)։

3. Միգրացիոն ադապտատորներ ՝ ww.ru/թարգմանիչներ 'v1 div2 "ծանր հաճախորդների համար։

4. Կանարեյկա 'հաճախորդների/տոպիկների/թեստերի խմբերով gateway-ում։

5. Sunset-պլանը 'ամսաթվերը, հաղորդակցությունը, ստենդները, թեստային տվյալները, օգտագործման պարամետրերը։

Պլատֆորմի և ենթակառուցվածքի դերերը

Schema Registry & Catalog-ը հետևի/սխեմաների ճշմարտության աղբյուրն է ածխաջրածինների պատմության հետ։

API Gateway/WindowMesh: Երթուղայնացում համաձայն, վերնագրեր, ճանապարհներ; rate-limit и auth per-version.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).

Observability: տարբերակը պետք է մտնի լոգայի/treiss/մետրիկայի մեջ։

Տարբերակների փորձարկումը

Schema-diff-ը PR-ում 'արգելափակել breaking-ը։

Consumer-Driven Corracom: պրովայդերը ստուգվում է իրական սպառողների մատակարարման դեմ։

Golden samples: Տարբերակի ստանդարտ պատասխանները։

E2E-կանարեյկա 'համեմատություն p95/p99, սխալներ և թայմաուտներ տարբերակների միջև։

Replay-ի իրադարձությունների համար, պրոյեկտները վերածվում են v2-ի առանց տարբերությունների։

Տվյալների և տեղեկատվության միգրացիան

REST/gRPC-ի համար, wwww.BD-ն արտադրվում է expand-and-www.ract-ի միջոցով (ավելացրեք սյունակը, սկսեք գրել ստանդարտ անցում և կարդալ հին)։

Events-ի համար 'dox-emit և կոնսուումերների միգրացիա։ երբեմն 'նոր պրոյեկտների վրա լոգոյի վերարտադրումը։

Մի արեք «մեծ պայթյուններ», փորձեք արձագանքել։

Կապ անվտանգության հետ

Scopes per version 'առանձին OIDC-scopes/դերեր v1/v2 համար։

Գաղտնիքները/claim 'a-ը պայմանագրի մի մասն է։ նրանց փոփոխությունը = major։

PII/PCI - մի ընդարձակեք payload առանց կարիքի։ նոր դաշտեր 'նվազագույն արտոնությամբ։

Antipatterns

Swagger-wash: ճշգրտումը նորարարված է, սերվերը 'ոչ (կամ հակառակը)։

Winobuf-tegs-ի վերարտադրումը տվյալների հանգիստ է։

Enum-իմաստների փոփոխությունը առանց major-ի։

Գլոբալ/v2 «կոսմետիկայի համար» 'տարբերակը առանց կոտրելու։

Մոռացե՞ լ եք sunset/usage-մետրիկները, անհնար է վերացնել հին տարբերակը անվտանգ։

Մեկ ընդհանուր տեղանունը տարբեր major-ի համար 'կարգերի և կոմպոզիցիաների խառնուրդ։

Chek-Slack առջև

• Փոփոխությունները ադիդիտիվ են կամ պատրաստվել են առանձին major-գիծ։
• Linters և schema-diff կանաչ (breaking չի թափվել)։
• Նորարարված MSK/օրինակներ/փաստաթղթեր, տեղադրումներ համատեղելիության մասին։
• Ներառված է toler.reader հաճախորդների մեջ; enum-fallback-ը փորձարկվել է։
• Major-run պլանը, հարմարվողները, կանարեյկան, sunset-ամսաթիվը և ուղարկումը։
• Metriki/logs/treiss պարունակում են տարբերակներ և հատվածներ դրա վրա։
• Կա նաև golden հավաքածուներ համեմատելու v1-v2։
• Իրադարձությունների համար, BACKWARD/FOX ռեժիմում սխեմաների ցանկը անփոփոխ է։

Ձևանմուշների օրինակներ

REST (URI + negotiation)

Երթուղի: 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 '(միջուկը) և "payron. enriched. v2 '(մանրամասները)։

Անցումային ժամանակահատվածի համար արտադրողը գնում է «v1» և «v2»։

FAQ

Ե՞ րբ է անհրաժեշտ «/v2 »։

Երբ փոխվում են ինվարանտները/սեմանտիկան, դաշտերը/մեթոդները հանվում են, փոխվում են բաղադրիչների ձևաչափը, կուսակցության բանալին, SLA/timings-ը այնպես, որ հաճախորդները կոտրվում են։

Դուք կարող եք ապրել առանց ակնհայտ տարբերակի REST-ում։

Միայն փոքր համակարգերի համար։ Արտաքին ինտեգրման համար ավելի լավ է ակնհայտ major գծերը։

Ո՞ րն է հնացած տարբերակը պահելու ժամանակը։

Կախված է էկոհամակարգից։ Արտաքին գործընկերների համար սովորաբար 6-12 ամիս է վաղ ծանուցմամբ և կանարեյով։

Ինչպե՞ ս է իրադարձությունների տարբերությունը տարբերվում API-ից։

Իրադարձությունները append-only են։ նոր սեմանտիկա = նոր տեսակի '.v2 "և dult-emit։ Կուսակցության բանալին պայմանագրի մի մասն է։

Արդյունքը

Տարբերակման ռազմավարությունները գործընթացն ու գործիքներն են 'ադիտիվ էվոլյուցիա լռելյայն, պարզ major-գծեր, capability-negotiation, dult-run և sunset։ Ավելացրեք ավտոմատացված ստուգումներ, փաստաթղթերի օգտագործման և կարգապահության հեռաչափություն, և ձեր API-ն արագ զարգանա, առանց «գիշերային միգրացիայի» և հաճախորդների անսպասելի անկումների։