Գնահատել նախագիծը
← Բոլոր հրապարակումները

Արժե՞ պահպանել REST «ստանդարտները»։ Ի՞նչ անակնկալ էր մեզ համար պատրաստել Apple-ի API-ն

REST API-ի նախագծումը մեծ մասամբ պաշտոնական ստանդարտ չունի։ HTTP սպեցիֆիկացիայից բացի, ունենք միայն լավ պրակտիկաներ, որոնք կարելի է ընդունել կամ անտեսել։

7 րոպե
APIRESTRest ApiAPI Design

Ներածություն

REST API-ները, հավանաբար, հանրային վեբ API-ների ամենատարածված հաղորդակցման մեխանիզմն են։ Երբ ձեռնամուխ եք լինում երրորդ կողմի ծառայության հետ ինտեգրմանը, կարող եք սպասել, որ գործ կունենաք REST-ի հետ։ Որոշ դեպքերում ստանում եք նաև SDK-ներ կամ Open API սահմանումներ, որոնք հեշտացնում են API-ի օգտագործումը. մյուսներում ձեզ մնում է միայն փաստաթղթավորումը։ Այսօր կդիտարկենք ստանդարտներն ու սպասելիքները, ինչպես նաև այն, ինչի կարելի է դեռ հանդիպել իրական API-ներում։

Վերջերս աշխատում էինք մեր հաճախորդներից մեկի նախագծի վրա։ Այն ներառում է շարժական հավելվածներ, որոնք ինտեգրվում են վճարային համակարգերի հետ, այդ թվում՝ Apple Wallet-ի։ Գնումը կատարվելուց հետո backend-ը վալիդացնում է գործարքը՝ լիցենզիաներ կամ խաղերի վիրտուալ արժույթ տրամադրելուց անմիջապես առաջ՝ համոզվելու համար, որ օգտատերն իսկապես վճարել է։ Սկսեցինք որոշ հետազոտությամբ և գտանք համապատասխան Apple-ի փաստաթղթերը, որոնք մեզ տարան ճիշտ API endpoint-ին։ Խոսենք այն մասին, թե ինչպես է այն նախագծված։

Նկատառում. մենք չգիտենք այս API-ի նախագծման ժամանակ կայացված տեխնիկական որոշումների հիմնավորումը։ Դա կարող է լինել հետադարձ համատեղելիությունը, հին համակարգերի հետ ինտեգրման կարիքը կամ որևէ նույնքան կարևոր գործոն։ Գուցե այն նույնիսկ նախատեսված չէ որպես REST, այլ պարզապես որպես «HTTP-API» – մեզ մնում է միայն կռահել։ Այդուհանդերձ, հարկ է նշել, որ այլ API-ներ հետևում են բոլորովին այլ նախագծման։

Richardson Maturity Model

Այս քննարկման շրջանակում արժե հիշատակել Richardson Maturity Model-ը, որը REST API-ի հասունությունը բաժանում է չորս մակարդակի։ Ահա շատ կարճ հիշեցում՝

  • Մակարդակ 0 – վեբ վրա հիմնված API-ի բազային մակարդակը։ Այստեղ կարող եք ունենալ, օրինակ, POST /createProduct endpoint։
  • Մակարդակ 1 – API ճանապարհները վերաբերում են ռեսուրսներին։ Ակնկալվում է, որ URI-ները գործածեն գոյականներ՝ բայերի փոխարեն, ուստի կտեսնեք այնպիսի ճանապարհներ, ինչպիսին /product/1-ն է՝ /createProduct-ի փոխարեն։
  • Մակարդակ 2 – HTTP բայերը օգտագործվում են ավելի ստանդարտացված ձևով – GET՝ տվյալներ ստանալու համար, POST/PUT՝ ստեղծելու համար և այլն։ Ապրանք ստանալու համար կկանչեք GET /product/1, իսկ ստեղծելու համար՝ POST /product։
  • Մակարդակ 3 – HATEOAS (Hypertext As The Engine Of Application State) – API-ի վերադարձրած ռեսուրսները մերկ ID-ների փոխարեն պարունակում են կապակցված ռեսուրսներին ուղղված URI-ներ։ Այսպիսի API-ները շատ հազվադեպ են, քանի որ առանց լրացուցիչ գրադարանների օգնության դրանք հակված են իրականացնելու համար չափազանց բարդ լինել։ Մեր նախորդ օրինակում GET /product/1 պատասխանը կպարունակեր հղումներ բոլոր կապակցված էնտիտիներին, և կարող էիք հետևել դրանց՝ ուսումնասիրելու ամբողջ տվյալների հավաքածուն։

Ամենից հաճախ մեր հանդիպած API-ները 2-րդ մակարդակի են։

HTTP բայը և endpoint-ի ճանապարհը

Վերադառնանք Apple-ի Verify Receipt endpoint-ին։ Առաջին բանը, որ աչքի է զարնում, հենց endpoint-ն է՝ POST https://buy.itunes.apple.com/verifyReceipt (մեծատառ-փոքրատառ զգայուն է)։ Դրա հիմնական խնդիրը կտրոնի տվյալները վերիֆիկացնելն է (շարժական հավելվածից ուղարկվող կոդավորված տող)։ Կարո՞ղ էր այն ավելի RESTful նախագծված լինել։ Տեսնենք։ Ճանապարհը ռեսուրսների վրա չի գործում (այն պարունակում է բայ), և մենք ուղարկում ենք POST, թեև իրականում ոչինչ չի ստեղծվում։ Փաստորեն, այն նման է 0-րդ մակարդակին։

Ինչպիսին կլիներ այլընտրանքային նախագծումը։ Դա այնքան էլ պարզ չէ, որքան թվում է։ Զրոյից սկսելիս դա կարող էր լինել GET հարցում query պարամետրով – GET, քանի որ իրականում մենք ստանում ենք գործարքի կտրոնը՝ գնված ապրանքի մասին տեղեկությամբ։ Բայց շարժական հավելվածից եկող կոդավորված կտրոնի տվյալները կարող են լինել 6000 նիշից երկար, մինչդեռ որոշ խորհուրդներ ասում են, որ query պարամետրերը պետք է մնան 2048-ից պակաս։ Էլ ի՞նչ կա։ HTTP 1.1 2014 սպեցիֆիկացիան իրականում թույլ է տալիս GET մարմնով։ Ցավոք, սպեցիֆիկացիան և իրականությունը երկու տարբեր բաներ են. REST client գրադարանների մեծ մասը պարզապես չի աջակցում դա, ուստի սա նույնպես լավ տարբերակ չէ։ Էլի՞ ինչ-որ բան։ Կարող ենք մտածել POST-ի մասին, որը ստեղծում է verification ռեսուրս – բայց, կրկին, հավանաբար ինչ-որ բան չի ստեղծվում ներսում։

Ինչպե՞ս է մրցակցությունը լուծում դա։ Դիտարկենք Google Play API-ն։ Այստեղ գտնում ենք

GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}.

Սա ակնհայտորեն ավելի RESTful է։ Փոխանցվող productId-ն և token-ը շատ ավելի կարճ տողեր են, քան Apple-ի կտրոնի տվյալները։ Հիմնական հարցն այն է, թե այս endpoint-ները իրականում ինչ են անում կուլիսներում – կարող ենք ենթադրել, որ Google-ը տվյալներ է կարդում DB-ից, մինչդեռ Apple-ը պարզապես վերծանում է տրված տվյալները մասնավոր բանալիով։ Եթե այդպես է, արդար համեմատությունը իրականում հնարավոր չէ։

Թեև որոշ նախագծային որոշումներ կարող են անակնկալ լինել, արժե հիշել, որ REST-ի մոդելավորումն ավելի դժվար է, քան կարող է թվալ։ Երբեմն չկա մեկ ճիշտ պատասխան, որը բավարարի բոլոր լավագույն պրակտիկաները։

Կարգավիճակի կոդեր

Այն, ինչ իսկապես զարմացրեց ինձ Apple-ի այս API-ում, կարգավիճակի կոդերն էին։ Մեր դիտարկած endpoint-ը միշտ վերադարձնում է 200 OK։ Սխալները գալիս են պատասխանի մարմնում՝ որպես status դաշտ – 0-ն նշանակում է վավեր, իսկ ցանկացած այլ արժեք՝ սխալ։ Ուրեմն ի՞նչ կլինի, եթե պատահաբար այդ endpoint-ին GET կանչեք։ 200 OK՝ մարմնում 21000 կարգավիճակով։ Իսկ եթե ուղարկեք անվավեր մուտք (օրինակ՝ մուտք, որը վավեր JSON չէ)։ 200 OK՝ մարմնում 21002 կարգավիճակով։ HTTP սպեցիֆիկացիաների համաձայն՝ 200 OK-ը ազդանշանում է, որ հարցումը հաջողվել է։ Մարդիկ վիճում են ինտերնետում, արդյոք ընդունելի է արդյոք մարմնում բիզնես սխալներով 200 OK վերադարձնելը (հարցումն ինքնին հաջողվում է, միայն տրամաբանությունն է ձախողվում), բայց իմ կարծիքով դա միանգամայն այլ իրավիճակ է, քան այստեղինը։ Անթույլատրելի HTTP մեթոդը ակնհայտորեն չի հիմնավորում 200 OK-ը։

Ինչպե՞ս է սա ազդում API-ի հետ աշխատանքի վրա։ Դա հաստատ այն չէ, ինչ մշակողը սկզբում կսպասի։ Որոշ խիստ տիպավորված REST client-ներ 200 OK-ը համարում են հաջողություն և փորձում են պատասխանը դեսերիալիզացնել տրված ձևաչափով։ Նման դեպքերը, իհարկե, կարելի է մշակել, բայց դա պահանջում է սովորականից մի փոքր ավելի ջանք։

Նշում. GraphQL հարցումների լեզուն նույնպես սպասարկվում է HTTP-ով։ Այնտեղ տարածված պրակտիկա է սխալները վերադարձնել նախապես սահմանված մարմնի ձևաչափով՝ 200 OK կարգավիճակի հետ։ Սակայն, կախված իրականացումից, որոշ սխալներ կարող են գալ այլ կարգավիճակի կոդերով։ Ինչպես տեսնում եք, HTTP-ն կարելի է օգտագործել բոլորովին տարբեր եղանակներով՝ կախված հաղորդակցության արձանագրությունից, «ստանդարտներից» և պրակտիկաներից։

JSON անվանման կոնվենցիա

Մեկ այլ բան իսկապես ստիպեց ինձ ինքս ինձ հարցնել՝ ինչո՞ւ։ Ահա թե ինչպիսի տեսք կարող է ունենալ հարցման մարմինը՝

{
   “receipt-data”: “...”, …
}

և ահա պատասխանը՝

{
   “status”: 0,
   “is_retryable: …,
   …
}

Նկատու՞մ եք տարբերությունը։ Հարցումները օգտագործում են kebab-case, իսկ պատասխանները՝ snake_case։ Կրկին, դրա հետ կարելի է ապրել, բայց որոշ json գրադարաններ ակնկալում են, որ ձեր օբյեկտները հետևեն մեկ ոճի։ JSON-ը բանալիների անվանման ստանդարտ չունի – որոշ ընկերություններ ընտրում են snake_case (օրինակ՝ GitHub-ը կամ Zalando-ն), մյուսները՝ camelCase (օրինակ՝ Apple-ի այլ API-ներ։ Ընտրությունը հաճախ կախված է օգտագործվող ծրագրավորման լեզվից։

Նույնականացում

API անվտանգությունը միշտ նշանակալի թեմա է։ REST API-ները նույնականացնելու շատ եղանակներ կան, որոնցից ամենատարածվածը բանալիները header-ներում փոխանցելն է։ Ավելի հին API-ները երբեմն բանալիները փոխանցում են query պարամետրերով (չի խորհուրդ տրվում) կամ հարցման մարմնում – և հենց դա է կատարվում այստեղ. մարմինը ներառում է password դաշտ։ Կրկին, ոչ ամենաբնորոշ մոտեցումը, բայց այնպիսին, որը կարող ենք ընդունել։ Այն հակված է ավելի շատ խնդիրներ առաջացնել backend-ում, քան client կողմում, քանի որ հարցման մարմինը պետք է դեսերիալիզացվի հարցումը նույնականացնելուց առաջ։ Բացի այդ, եթե ձգտում եք հետևողական API-ների, ի՞նչ եք անում GET endpoint-ի հետ, որը նախընտրելի է, որ մարմին չունենա (տե՛ս HTTP բայերի մասին նախորդ բաժինը)։

Եզրակացություններ

REST API-ի նախագծումը մեծ մասամբ պաշտոնական ստանդարտ չունի։ HTTP սպեցիֆիկացիայից բացի, ունենք միայն լավ պրակտիկաներ, որոնք կարելի է ընդունել կամ անտեսել։ Իմ կարծիքով, հետևողականությունն ու բարձրորակ փաստաթղթավորումը մնում են ամենակարևոր գործոնները, քանի որ դրանք պարզապես հեշտացնում են API-ի հետ աշխատանքը։ Ընկերությունները փորձում են փաստաթղթավորել իրենց ուղեցույցները, բայց ինչպես ցույց են տալիս Zalando-ի, Google Cloud-ի կամ GitHub-ի օրինակները, դրանք կարող են հսկայական դառնալ։ Կրկնեմ. REST API-ն նախագծելը ամենահեշտ գործը չէ։

API ստեղծելիս հիշեք դրա օգտատերերին։ Այնպիսի ռեսուրսները, ինչպիսին Open API սպեցիֆիկացիան է, չափազանց օգտակար են – կարող եք այն օգտագործել Postman-ի հետ կամ ընտրված լեզուների համար client գրադարաններ գեներացնելու համար։ Sandbox միջավայրը կամ առանց լրացուցիչ կարգավորման աշխատող օրինակային հարցումները նույնպես հիանալի հավելումներ են, որոնք պարզապես հեշտացնում են գործը։

Apple-ի verify receipt API-ի նախագծումը հաստատ առանձնանում է և կարող է շփոթեցնող լինել իր օգտատերերի համար։ Ինչպես նշվեց վերևում, մենք չգիտենք այս նախագծման պատճառները – կարող ենք միայն ենթադրել, որ լավ պատճառներ եղել են։