API և նորարարության համատեղելիությունը

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

Diitive-first: ավելացրեք նոր, առանց կոտրելու հինը (նոր oporative դաշտեր/endpoints, նոր enum-արժեքներ)։

Կայուն պայմանագրեր. <<Ինչ է խոստացված ճշգրտման մեջ և աշխատում>>։ վարքագիծը փաստագրված է։

Backward> Forward 'հետադարձ փոխանցման գերակայություն; forward-ը պատրաստված է toler.ru-readers-ի միջոցով։

Փաստաթղթերը առաջնային են 'ճշմարտության միակ աղբյուրը registry (OpenAPI/AsyncAPI/Delo) սխեմայի տարբերակն է։

Ակնհայտ էվոլյուցիա 'breaking-ը միայն նոր major-տարբերակի և միգրացիոն ուղեցույցի միջոցով է։

2) Փոփոխությունների տաքսոնոմիա

2. 1 Համատեղելի (MINOR/PATCH)

Սպիտակուցային դաշտերի ավելացումը/հեդերը, նոր էնդպոինտները, query-express-ը դեֆոլտներով։

Լիմիտների ավելացումը («page _ size», TTL), սխալների հստակեցումը առանց պարամետրերի/սեմանտիկայի փոփոխության։

Էնումի արժեքների ավելացումը, եթե հաճախորդները անտեսում են «անծանոթ» (toler.ru-reader)։

2. 2 Երկիմաստ (Behavioral)

Դեֆոլտների փոփոխությունը, տեսակավորման կարգը, բարակ թայմաուտները, քվոտը կարող է «կոտրել» բիզնես տրամաբանությունը։ Պահանջում է RFC + անոնսը և կանարեկները։

2. 3 Կոտրող (MAJOR)

Դաշտերի վերանվանումը/հեռացումը, տեսակը/ձևաչափը, այլընտրանքային սխալների փոխարինումը, հակառակ անհամատեղելիությունը/սխեմաները։

3) Տարբերակման քաղաքականությունը

Ռազմավարություն '«path versioning» («/v1 », «/v2»)։

Minor/patch: «ավելացրեք, մի կոտրիր»։

Թվագրված վերնագրերը (դոպը) '«X-API-Version-Date» փափուկ աստիճանական փոփոխությունների համար։

Մեդիա տեսակներ (opz.) : `Accept: application/vnd. acme. v1 + json "բարակ գրանտի համար։

4) Դեպրեսիաներ և sunset

4. 1 Հաղորդակցման վերնագրեր

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

4. 2 Ելույթի կարգը

1. Հայտարարությունը պորտալում/հաղորդագրությունում/MSK rele.notes-ում։

2. Նախազգուշացման պատուհանը 90-180 օր է։

3. Dashborde adoption-ի կարգավիճակները։

4. Sunset-ից հետո 410 Gone-ը կամ «read-only» ռեժիմը grace ժամանակահատվածի համար, եթե համաձայնված է։

5) Մոսկվան և տարբերակների համատեղ գոյությունը

Dance-write/dult-read անցումային ժամանակահատվածում և զեկույցներով։

Ադապտերները (ժամանակավոր) 'հին payload-ի gateway-վերափոխումները նոր սխեմաներ են։ հարմարվողի կյանքի տևողությունը սահմանափակ է։

MSK օգնություն ՝ երկու տարբերակները աջակցող օրինագծեր, ավանդի նախազգուշացումներով (1 անգամ ընթացքի համար)։

Ֆիչա դրոշը 'նոր սեմանտիկայի իրականացումը 2019/տենանտների ցուցակով։

6) Backward և forward համատեղելիությունը

6. 1 Backward (հին հաճախորդները նոր սերվերն են)

Մի փոխեք տեսակների/պարտավորության պարամետրերը։

Նոր դաշտերը միայն օբյեկտիվ են։

Սխալները նախկին «error _ code» են, նոր ստանդարտ ավելացրեք, չփոխեք։

6. 2 Forward (նոր հաճախորդները հին սերվերն են)

Ստուգել հնարավորությունների առկայությունը (capabilities) «OPTIONS '//versions» միջոցով։

Գրեյս վարքագիծը 'հաճախորդը պետք է հանդուրժի բացակայող ավարտներին։

7) Պայմանագրեր և ավտոմատ ստուգումներ

Registry: Մենք ենք սխեմաների տարբերակները։ PR-դիֆերը բացատրում են «breaking/non-breaking» զեկույցները։

Լինթեր ՝ անուններ/տեսակներ, կուռքեր, պագինացիա, կայուն բջիջներ։

CDC (Consumer-Driven Corracom) 'CI-ում ինտեգրատորների թեստեր (Pact և անալոգներ)։

Գեյթ 'PR-ն արգելափակված է breaking-ով առանց' major bump '/RTS-ի։

CI-2019 օրինակ

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

8) Կանարյան արտադրությունը և հակառակ քայլը

Canary: 10 տոկոսը 25 տոկոսն է, 50 տոկոսը 3,100 տոկոսն է։ SLO-ի վատացման ժամանակ (5xx/latency/429)։

Բետա-բանալիներ 'allowlist-ի նոր տարբերակների հասանելիությունը։

Release freeze 'error-budget այրման ժամանակ։

Ընդունման վերլուծությունը 'հաճախորդների մասնաբաժինը նոր տարբերակով, հաճախորդի ժամանակը։

9) Մանրամասների համատեղելիությունը 'սխալներ, պագինացիաներ, գաղափարախոսություն

9. 1 Սխալներ

Չփոխեք HTTP ստատուսները գոյություն ունեցող սցենարներում։

«error _ code» կայուն; նոր պլանավորվում է միայն ավելացնել։

«Apple/problem + json» -ը միասնական ձևաչափ է։

9. 2 Պագինացիա

Անցումը cursor/keyset = MINOR-ին, եթե աջակցվում է հին 'set/limit "։

Փաստաթղթավորեք տեսակավորումը «(wwww.ated _ at, id)» և ռուսական կուրսորը։

9. 3 Idempotency

Write-ի համար '"Idempotency-Key '+" 49IDEMP _ REPLAY "հակամարտության ժամանակ։

Մոսկվան չպետք է փոխի կուռքերի իմաստը։

10) Gateway-տրանսֆորմացիան (երբ տեղին է)

Map v1-v2 դաշտեր, նորմալացնել սխալները, փոխակերպել www.dat/փողի։

Guardrails: Փոխակերպումները թափանցիկ են և տրամաբանվում են։ մի թաքցրեք breaking, այլ օգտագործեք որպես կամուրջ սահմանափակ ժամանակով։

11) Հաղորդակցություն և պորտալ

Changelog с датами (`added/changed/deprecated/removed/fixed`).

Տարբերակի քարտը 'կարգավիճակ (beta/GA/deprecated), sunset ամսաթիվը, հղումները։

Վեբհուկի ծանուցումները '"deprecation։ notice`, `version. released`, `plan. change`.

MSK rele.notes + դրոշը պորտալում։

12) Հաջողության մետրերը

Adoption rate v2 (խնդրանքով/հաճախորդներին)։

Backward-compat incidents (col-w-vo «կոտրվածք»)։

Error mix (4xx/5xx/429) մինչև/հետո։

Time-to-Adopt-ը միջին է։

Supronload (թիկետներ/105)։

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 կանաչ
• Express/MSK նորարարված (օրինակներ/օրինակներ)
• Կանարեյկա + SLO-ում
• Կոմմ պլան, էջ պորտալում
• Dashbords adoption և սխալներ

MAJOR

RFC/ADR, sunset ամսաթիվը և պատուհանը 90-180 օր։

• v1-v2 կամուրջ (gateway) և միգրացիոն ուղեցույց
• Dance-write/read և ծալքեր
• DRK երկու API + նախազգուշացումով
• Օդաչուն հիմնական ինտեգրատորներով

15) Իրականացման պլանը (3 իտացիա)

1. Հիմքը (երկու շաբաթ)

Registry սխեմաները, ոսպնյակը և www.diff CI-ում; քաղաքականությունը։ վերնագրեր «Deprecation/Sunset»։

2. Կառավարվող ուլտրաձայնները (3-4 շաբաթ)

Կանարեյկի, ֆիչի դրոշները, SLO-ալերտները։ տարբերակների պորտալը; MSK-ենթախմբերը երկու ճյուղերի աջակցությամբ։

3. Ավտոմատիզացիան և մասշտաբը (անընդհատ)

CI սպառողների թեստեր, sunset կանխատեսում adoption, ավտոմատ նոտացիա և հիշեցումներ։

16) Mini-FAQ

Կարո՞ ղ եք փոխել դաշտային տեսակը առանց major

Ոչ։ Նույնիսկ «տողը նշված թիվ» - breaking։ Մուտքագրեք նոր դաշտ, հինը 'deprecate։

Էնում 'կարո՞ ղ եք ավելացնել արժեքները։

Այո, եթե հաճախորդները toler.ru-readers են։ Հակառակ դեպքում, նախ տեղեկացումը և բետա։

Որքա՞ ն պետք է պահել հին տարբերակը։

Մինչ adoption նոր 3695 տոկոսն է և պահպանվում է տեղավորման պատուհանը։ Գրանցեք ժամանակը քաղաքականության մեջ։

Արդյունքը

API-ի համատեղելիությունը կարգապահությունն է 'diitive-մոտեցում, ֆորմալ սխեմաներ և դիֆեր, կանարեկուլներ, պարզ դեպրեսիաներ և կառավարվող ձեռնարկություններ։ Ամրագրեք փոփոխության քաղաքականությունը, ավտոմատիզացրեք ստուգումները և հաղորդակցությունները, ստուգեք adoption, և ձեր նորարարությունները կդադարեն կոտրել հաճախորդներին, իսկ էվոլյուցիայի արագությունը կաճի առանց հուսալիության։