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

Ինչու՞ է անհրաժեշտ պայմանագրային համատեղելիություն

Պայմանագրային համատեղելիությունը API-ի կարողությունն է զարգացնել առանց գոյություն ունեցող ինտեգրման խզման։ Աճող API համակարգերում փոխվում են հաճախորդների կոդի ավելի հաճախ։ համատեղելիությունը թույլ է տալիս, որ ֆիտերատիվորեն արտադրեն առանց «մեծ տեղափոխությունների»։

Հիմնական գաղափարը 'պայմանագիրը առաջնային է, փոփոխությունները կատարվում են մրցույթի կանոններով և ինքնաբերաբար ստուգվում են։

Հիմնական հասկացությունները

Պայմանագիրը ինտերֆեյսի պաշտոնական ճշգրտումն է 'ռեսուրսներ/մեթոդներ/իրադարձություններ, տվյալների սխեմաներ, սահմանափակումներ, SLA, անվտանգության պահանջներ։

Մատակարարը (provider) API-ի սեփականատերն է։ Սպառողը (consumer) հաճախորդն է/ինտեգրումը։

Համատեղելիությունը

Backward: Նոր մատակարարը աշխատում է հին սպառողների հետ։

Forward: Հին մատակարարը աշխատում է նոր սպառողների հետ (սովորաբար հասնում է «համբերատար ընթերցողների»)։

Fox: Ինչպես backward, այնպես էլ forward (ամենաուժեղ տարբերակը)։

Ադելիտիվությունը առանց գոյություն ունեցող տարրերի ավելացումն է։

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

Semantic Versioning (խորհուրդ)

MAJOR-ը կոտրող փոփոխություններ է (միայն API-ի նոր գիծ արտադրելիս '' '</v2>,')։ v2`).

MINOR-ը ադիտիվ փոփոխություններ է (նոր ալգորիթմային դաշտեր/մեթոդներ)։

PATCH - առանց պայմանագրի փոփոխության։

Deprecation Policy 'հնացած տարրերի հայտարարությունը, աջակցության պատուհանը (sunset), վերնագրերում/մետատվյալներում նախազգուշացումները, հեռացման պլանը։

Անվտանգ vs վտանգավոր փոփոխություններ

Անվտանգ (սովորաբար backward-compatible)

JSON/Medobuf/Avro-ում միգրացիոն դաշտի ավելացումը։

Նոր էնդպոինտի/մեթոդի/իրադարձությունների ավելացումը։

Enum-ի ընդլայնումը նոր արժեքներ, եթե սպառողները հանդուրժում են անհայտ արժեքներին։

Լիմիտների բարձրացումը (օրինակ ՝ «www.Items») առանց նվազագույն խստացման։

Nullable-ի ավելացումը ճիշտ դեֆոլտներով։

Նկարագրության/օրինակների տեքստի փոփոխությունը։

Վտանգավոր (կոտրում են համատեղելիությունը)

Փոխակերպել/հեռացնել դաշտերը, փոփոխել նրանց տեսակը կամ պարտավորությունը։

Սեմանտիկայի փոփոխությունը կարգավիճակը-105/սխալ է (օրինակ ՝ «200», դարձավ «204» կամ «404»)։

Լուծիչների ձևաչափի փոփոխությունը (UUID entint)։

Վալիդացիայի խստացումը (ավելի խիստ նվազագույն/պաթթերներ) առանց վարկածի։

Կարգի և կառուցվածքի փոփոխությունը gRPC-strimes/իրադարձությունների մեջ։

Նոր դաշտերի համար Corobuf-ում թեստերի համարները փոխակերպելը։

Փոխազդեցության ոճերի համատեղելիությունը

REST/HTTP + JSON Schema

Addimation: Նոր դաշտերը սահմանվում են որպես «optional »/« nullable»։

Toler.Reader-ը հաճախորդի մոտ 'անտեսել անհայտ դաշտերը։ ապավինել կարգին։

Տարբերակումը 'մաժորը ճանապարհին ('/v2 «) կամ մեդիատիպում (» applations/vnd. example. v2+json`).

ETag/If-Match 'անվտանգ ապդեյտների համար առանց մրցակցության։

Սխալները 'մեկ ձևաչափ («type», «code», «title», «detail», «trace _ id»), մի փոխեք «code» արժեքները առանց մաժորի։

Պագինացիա 'կուրսորները ավելի նախընտրելի են, քան set; ավելացրեք դաշտերը «next _ cursor», մի փոխեք գոյություն ունեցող իմաստը։

gRPC / Protobuf

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

Նոր դաշտերը '"optional '/" repeated", սերվերի խելացի դեֆոլտներով։

Մի փոխեք հաղորդագրությունների կարգը և պարտավորությունը streaming-RPC-ում։

Սխալների ստատուսները կայուն են («MSALID _ ARGUMENT», «FAILED _ PRECONDIM» և այլն); նոր սեմանտիկան բացատրում է մեթոդի նոր տարբերակը/108։

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON Schema

Իրադարձությունների անվանումը '"domain. action. v{major}`.

Նոր դաշտերը օպորացիոնալ են։ հատկացրեք միջուկը և հարստացումը («.enriched»)։

Սխեմաների գրանցումները 'կոդավորման կանոնները (BACKWARD/FORWARD/FOX) թեմայով/իրադարձության մասին։

Enum-ի ընդլայնումը թույլատրելի է սպառողների կողմում։

Խմբավորման/կարգի ստեղնաշարի փոփոխությունը ագրեգատի համար = կոտրող փոփոխություններ։

GraphQL

Դաշտերի/տեսակների ավելացումը անվտանգ է։ / հեռացումը միայն @ deprecated և պատուհանի միջոցով։

Մի փոխեք տեսակները/nullable առանց մաժորի։

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

Կայուն էվոլյուցիայի արտոնագրերը

Delitive-first: Ընդարձակեք առանց կոտրելու։

Capability negotiation: հաճախորդները ասում են, որ աջակցում են (վերնագրեր/պարամետրեր/պայմանագրեր), սերվերը հարմարվում է։

Պայմանագրի սահմանները 'գրանցեք MGC (նվազագույն երաշխիքային պայմանագիր) և բաժանեք ընդլայնումը (հետադարձ բուրգի մոդել)։

Tolerensby-ը բացատրում է. Հաճախորդները անտեսում են ավելորդ և ճիշտ կերպով վերարտադրում անհայտ արժեքները enum (fallback)։

Dance-write/Dance-emit: մաժորային փոփոխությունների ժամանակ որոշ ժամանակ արտադրեք «v1» և «v2» զուգահեռ։

Sunset headers/Events: Նախապես տեղեկացրեք տարբերակների հեռացման մասին։

Governational և ավտոմատիզացիա

API-liners

OpenAPI/Spectral: Անուններ, պագինացիաներ, սխալներ, դաշտեր։

Buf/Eurobuf 'վերաիմաստավորման արգելք, կոդավորման նոտաներ։

AsyncAPI/Schema Registry-ը CI-ի մակարդակում սխեմաների համատեղելիությունն է։

Կոդավորման կատալոգը (SSOT) 'կենտրոնացված սխեմաների/տարբերակների տեղադրումը ածխաջրածինների պատմության հետ։

API Guild: գիլդիա/հանձնաժողովը, որը ընդունում է կանոններ, ձևանմուշներ և փոփոխություններ։

Change Live: RFC/ADR, rele.notes, միգրացիոն սկավառակներ։

Փորձարկումներ 2019

Schema-diff-ը CI-ում 'մենք արգելափակում ենք քնի կոտրող փոփոխությունները (OpenAPI-diff, Buf breaking, SR compatibility)։

Consumer-Driven Corrac.ru (CDC): Pact/նմանատիպ - հատուկ սպառողների մատակարարման դեմ պատժամիջոցների ստուգում։

Golden samples: Ստանդարտ հարցումներ/պատասխաններ և ռեգրեսիայի իրադարձություններ։

E2E Canary: Records-ը/առանձին կոնսումմերի խմբերը։

Chaos/latency: Թայմաուտների/ռեգրերի ստուգումը, latency-SLO-ի փոփոխությունը համարվում է պայմանագրի փոփոխություն։

Lenta.ru և դեպրեքեյթ

1. Հայտարարեք դեպրեսիտ 'նշեք տարրը, նշեք sunset-ի ժամկետը և այլընտրանքը։

2. Աջակցեք կոմպոզիցիաների ժամանակահատվածը 'drix-write/drone-emit, կամուրջներ, ադապտերներ։

3. Հավաքեք հեռուստացույց, ո՞ վ է օգտագործում հինը։

4. Հաղորդակցություն 'հաղորդագրություններ, ռելիզային նոտաներ, թեստային ստենդներ։

5. Հեռացում 'պատուհանի երկարությամբ' ֆիքսված ֆոսֆորով հեռացում։

Փոփոխությունների օրինակներ

REST

Կար

json
{ "id":"p1", "status":"authorized" }

Նա դարձավ (ադիդիտիվ, անվտանգ)

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

Հաճախորդները, որոնք անտեսում են անհայտ դաշտերը, չեն կոտրվում։

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Event

`payment. authorized. v1 '(միջուկը) + "payron. enriched. v1 '(հարստացում)։ Կրիտիկական ճանապարհի սպառողները կարդում են միջուկը և կախված չեն հարստությունից։

Antipatterny

Swagger-wash: Կառուցվածքային կերպով գոյություն ունի, բայց գործընկերության վարքագիծը տարբերվում է դրանից։

Breaking by stealth: փոխեցին տիպը/կարգավիճակը/ձևաչափը առանց նոր տարբերակի և պատուհանի։

Հում CDC իրադարձությունները որպես հանրային պայմանագիր 'BD սխեմաների արտահոսք, էվոլյուցիայի անհնարինություն։

Կոշտ հաճախորդը 'ընկնում է անհայտ դաշտերում/արժեքներով։ toler.reader-ի բացակայությունը։

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

Լատինականությունը որպես «ոչ կոնտակտային», անսպասելիորեն p95 - սպառողները կոտրում են թայմաուտները։

Chek-Light 2019 (Merjem)

• Ադդիտիվ փոփոխությունները (կամ մաժորի տարբերակը պատրաստված է)։
• Linters/www.cheks անցան, մրցույթի կանոնները կանաչ են։
• Սխալները/108/ստատուսները չէին փոխում սեմանտիկան։
• Enum-ն ընդլայնված է առանց հին արժեքների։ հաճախորդները toler.ru են։
• MGC սահմանները անփոփոխ են։
• Նորարարված օրինակներ/MSK։
• Մաժորի համար 'dult-write/dult-emit, sunset-ամսաթիվը, կոմմ պլանը։
• CDC/Golden/E2E թեստերը անցան։

FAQ

Ինչպե՞ ս է backward տարբերվում forward-ից։

Backward, նոր սերվերները չեն կոտրում հին հաճախորդներին։ Forward-ը, նոր հաճախորդները չեն կոտրվում հին մրցույթների վրա (toler.reader-ի և կոկիկ դեֆոլտների միջոցով)։

Ե՞ րբ անել «/v2 »։

Երբ փոխվում են ինվարանտները/սեմանտիկան, դաշտերը/մեթոդները հանվում են, անհրաժեշտ է անվտանգության նոր մոդել, ավելի հեշտ և ազնիվ նոր գիծ։

Կարո՞ ղ եք ապրել առանց Schema Registry/ոսպնյակների։

Տեսականորեն, այո, գրեթե հաճախակի ռեգրեսիաներ են և «թաքնված» կոտրվածքներ։ Ավտոմատիզացիան ավարտվում է։

Արդյո՞ ք Էնումը կարող է ընդլայնվել։

Այո, եթե հաճախորդները ճիշտ մշակում են անհայտ արժեքներ (fallback/ignore)։ Հակառակ դեպքում 'մաժոր։

Արդյունքը

Պայմանագրային համատեղելիությունը + կարգապահությունն է + ավտոմատիզացիան։ Նախագծեք ադիդիտիվ, տարբերեք կոտրող փոփոխությունները, օգտագործեք toler.rader, ավտոմատ ստուգեք օրինագծերը և CDC-ը, պլանավորեք դեպրեքեյթ։ Այսպիսով, API-ն կարող է արագ զարգացնել, իսկ ներմուծումը ՝ կայուն մնալ։