Պահեք ձեր API-ն պարզ. արդյունավետության և հեշտ օգտագործման ճանապարհը
API-ն գործիքի մուտքի կետն է, ուստի կարևոր է վերահսկել դրա բարդությունը։ Երբ ձեր բիզնեսը կախված է API ծառայություններից, պարզությունը կարող է դառնալ մրցակցային առավելություն։
Գործիք ընտրելիս պետք է կշռադատենք՝ որքան է այն արժե և որքանով է բավարարում մեր կարիքները։ Այն պետք է անի այն, ինչ սպասում ենք, և անի լավ։ Երբեմն, եթե երկու գործիք հավասարապես հնարավորություններ ունեն, պարզն ավելի լավ ընտրություն է, քանի որ խնայում է ժամանակ։ API-ն գործիքի մուտքի կետն է, ուստի կարևոր է վերահսկել դրա բարդությունը։ Երբ ձեր բիզնեսը կախված է API ծառայություններից, պարզությունը կարող է դառնալ մրցակցային առավելություն։
Այս հոդվածում քննարկվում է, թե ինչպես է չափից ավելի բարդացումը խնդիրներ առաջացնում API-ներում։ Կդիտարկենք, թե ինչն կարող է բարդացնել API-ն, այդ թվում՝ ինչ պետք է այն անի և ինչպես է նախագծված։ Հոդվածը կօգնի ձեզ.
- խուսափել ավելորդ բարդացումից,
- բացահայտել բարդացման աղբյուրները,
- պարզեցնել առկա լուծումները և դարձնել դրանք ավելի արդյունավետ։
Ի՞նչ է բարդացումը
Նախ պետք է հստակեցնենք, թե իրականում ինչ է նշանակում բարդացում։ Բառարանը բարդացումը սահմանում է այսպես.
մի բան, որը իրավիճակը դարձնում է ավելի դժվար, կամ այդ գործողությունն ինքնին
API-ների դեպքում սա ներառում է ամեն ինչ, ինչը API-ն դարձնում է օգտագործման կամ ստեղծման համար ավելի դժվար։
Նկատի ունեցեք, որ «բարդացում» և «բարդություն» (complexity) հաճախ օգտագործվում են որպես հոմանիշներ, թեև դրանց իմաստները փոքր-ինչ տարբեր են։ Complexity բառը բառարանում նայելիս տեսնում ենք, որ այն վերաբերում է.
բազմաթիվ մասերից բաղկացած լինելու և հասկանալու կամ լուծելու համար դժվար լինելու վիճակին
API-ների դեպքում բարդությունը կարող է վերաբերել կառուցվածքին (օրինակ՝ endpoint-ների, header-ների և հաղորդագրության մարմնի ատրիբուտների քանակին) կամ API-ի հետևում թաքնված համակարգին (օրինակ՝ մոդուլների կամ միկրոսերվիսների քանակին)։ Բարդությունը, անշուշտ, այն բաներից է, որոնք կարող են հանգեցնել բարդացման։
Այս տարբերության պատճառով հոդվածի մնացած մասում հիմնականում կխոսենք «բարդացման», այլ ոչ թե «բարդության» մասին։ Այս եզրը ընտրել եմ, որպեսզի ընդգծեմ այն առանձնահատուկ խնդիրներն ու դժվարությունները, որոնք կարող են առաջանալ API-ներ նախագծելիս և օգտագործելիս։
Չափից ավելի բարդացած API-ի խնդիրները
API-ի բարդացումից կարող են առաջանալ բազմաթիվ խնդիրներ։ Ամենահաճախ հանդիպողներն են.
| API ինտեգրատորի տեսանկյունից | API մատակարարի տեսանկյունից |
| Ինտեգրացիաները հաճախ ձախողվում են | Թեստավորումը խնդրահարույց է |
| Փաստաթղթերը կարդալու վրա շատ ժամանակ է գնում | Մոնիտորինգը դժվար է |
| API-ի աջակցման թիմին հարցումների մեծ քանակ է գալիս | Մասշտաբավորումը դժվար է |
| Ինտեգրացիաները երկար են տևում | Ինտեգրատորների հարցումների մշակման վրա շատ ժամանակ է գնում |
| Սպասարկումը մեծ ջանք է պահանջում | Նոր հնարավորությունները երկար են մատակարարվում |
| Սպասարկումը մեծ ջանք է պահանջում |
Երբ նկատում եք այս ախտանիշներից որևէ մեկը, կարևոր է պարզել՝ ինչ է թաքնված դրանց հետևում, և ստուգել՝ արդյոք դրանք API-ի բարդացումից են։ Եթե այո, մի պահ մտածեք, թե ինչպես է ձեր API-ն այդքան խճճվել։ Այդ մտորումը արմատական պատճառը վերացնելու կամ առնվազն դրա ազդեցությունը արդյունավետ սահմանափակելու բանալին է։
Հետևյալ բաժիններում դիտարկվում են այն գործոնները, որոնք ազդում են API-ի բարդացման վրա։
API-ի բարդացման գործոնները
API-ն բարդացնող բաներն այնքան շատ են, որ դրանք բոլորը մեկ հոդվածում թվարկելն ու նկարագրելը գործնականում անհնար կլիներ։ Սակայն դրանք համարյա բոլորը մտնում են հետևյալ խմբերից մեկի մեջ.
- Ֆունկցիոնալ պահանջներ. այն ամենը, ինչ սպասվում է առաջարկվող ֆունկցիոնալության առումով։
- Ոչ ֆունկցիոնալ պահանջներ. այն ամենը, ինչ սպասվում է արտադրողականության, հուսալիության, անվտանգության և որակի այլ հատկանիշների առումով։
- API-ի վատ կառուցվածք. API-ի բաղադրիչների, endpoint-ների և փոխազդեցությունների ոչ ամենաօպտիմալ նախագծումն ու դասավորությունը։
Այնուհետև կանցնենք այս խմբերից յուրաքանչյուրով՝ ընդգծելով դրանց առանձնահատուկ դժվարություններն ու հարակից նկատառումները։
API-ի տրամադրած ֆունկցիոնալությունը
API-ը գոյություն ունի հիմնականում ինտեգրատորների համար ֆունկցիոնալություն բացելու նպատակով։ Սակայն հնարավորությունների քանակի աճի հետ API-ն կարող է ավելի ու ավելի բարդանալ։ Այդ իսկ պատճառով API-ում ներառվող ֆունկցիաների ընտրությունը լուրջ ուշադրություն է պահանջում։ Սովորաբար որոշումը թելադրում է այն, ինչ հաճախորդներն ամենաշատն են խնդրում, բայց կարելի է հաշվի առնել նաև այլ հանգամանքներ, օրինակ՝ թե որքանով է հնարավորությունը համահունչ API մատակարարի բիզնես ռազմավարությանը։
Պարզ դարձնելու համար վերցնենք գրախանութի API-ի օրինակը։ Այստեղ մենք բացում ենք endpoint, որը վերադարձնում է հասանելի գրքերը գներով՝ API հաճախորդի ընտրած արժույթով, որը փոխանցվում է այս query պարամետրով.
GET /book-store-api/books?price.currency=USD
{
"books": [
{
"id": "04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets to writing pristine,
maintainable, and efficient code that stands the test of time.
Discover essential principles, patterns, and best
practices that empower you to create software that is
not only functional but also a joy to read and work with.
Take your programming skills to the next level
with this indispensable guide to achieving clarity,
simplicity, and excellence in your code."
},
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide to mastering
the art of pragmatic software development. Learn how
to approach coding challenges with a practical
mindset, leverage powerful tools, and adopt
efficient techniques that lead to success in
any programming project. Unravel the secrets
of effective team collaboration, debugging,
and problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world advice,
this book is your roadmap to becoming
a truly pragmatic programmer."
}
]
}
Հաճախորդին գնի արժույթն ընտրելու հնարավորություն տալը այստեղ բարդացնում է API-ն և բերում է հետևյալ դժվարությունները.
- Արժույթների տատանումներ. Քանի որ գրքերի գները կախված են փոխարժեքներից, դրանք կարող են անկայուն լինել, ինչը կարող է նշանակել, որ հաճախորդները տեսնում են անհետևողական գներ։
- Վերադարձի քաղաքականության բարդություն. Տարբեր արժույթներով գնումների համար վերադարձի քաղաքականությունը կարող է բարդանալ, քանի որ վերադարձվող գումարը կարող է փոխվել փոխարժեքների հետ մեկտեղ։
- Փոխարժեքների մեխանիզմ. Ինչ-որ բան պետք է ստանա և կառավարի փոխարժեքները, որպեսզի արժույթների փոխարկումները ճիշտ լինեն։
- Ձախողումների մշակում. Փոխարժեքներ ստանալու սխալները պետք է մշակվեն սահուն կերպով, որպեսզի ծառայությունը չխաթարվի։
Այս բոլոր դժվարություններին հնարավոր է հաղթահարել, բայց կարևոր է ուշադիր մտածել՝ արդյոք API-ն մի քանի արժույթով առաջարկելու բիզնես արժեքը արդարացնում է վերը թվարկված ծախսերն ու դժվարությունները։
Այստեղ դասը հետևյալն է. զգույշ եղեք, երբ որոշում եք, թե որ հնարավորություններն ստեղծել։ Յուրաքանչյուր նոր ֆունկցիոնալություն իր գինն ունի, և այդ գինը հաճախ գերազանցում է իրականացման ծախսը։ Անհրաժեշտ է մանրակրկիտ մտածել, որպեսզի գտնվի հավասարակշռությունը արժեք մատակարարելու և API-ի բարդությունը վերահսկողության տակ պահելու միջև։
Ոչ ֆունկցիոնալ պահանջներ
Ոչ ֆունկցիոնալ պահանջները վերաբերում են համակարգի ընդհանուր հատկություններին, որոնք անմիջականորեն կապված չեն կոնկրետ ոլորտի հետ։ Մարկ Ռիչարդսի և Նիլ Ֆորդի «Fundamentals of Software Architecture» գրքում դրանք կոչվում են ճարտարապետական բնութագրեր և նկարագրվում են այսպես.
համակարգի էական կողմերը, որոնք կախված չեն խնդրի ոլորտից
Հեղինակները նաև ընդգծում են, որ այս պահանջները պետք է նվազագույնի հասցվեն, այլ ոչ թե կուտակվեն.
Հավելվածը կարող է տրամադրել ճարտարապետական բնութագրերի հսկայական քանակ, բայց չպետք է։ Յուրաքանչյուր աջակցվող բնութագիր նախագծումը դարձնում է ավելի բարդ։ Այդ իսկ պատճառով ճարտարապետի հիմնական պարտականություններից մեկն է ընտրել հնարավորինս քիչ ճարտարապետական բնութագրեր, այլ ոչ թե հնարավորինս շատ։
Ես լիովին կիսում եմ այս տեսակետը։ Յուրաքանչյուր ոչ ֆունկցիոնալ պահանջ կարող է API-ն ավելի բարդացնել։ Ստորև կդիտարկենք մի քանի ոչ ֆունկցիոնալ պահանջներ՝ հասանելիություն, պատասխանատվություն, արտադրողականություն, հետադարձ համատեղելիություն, դյուրատեղափոխելիություն և անվտանգություն, և կվերլուծենք, թե ինչպես կարող է դրանցից յուրաքանչյուրը բարդացնել API-ն։
Հասանելիություն
Հասանելիությունը նշանակում է արտադրանքներ, ծառայություններ կամ թվային բովանդակություն նախագծել այնպես, որ հնարավորինս շատ մարդիկ կարողանան դրանց հասնել և օգտվել դրանցից։ Տեսնենք, թե ինչպես կարող է ինտերնացիոնալիզացիայի ավելացումը ձեր API-ն դարձնել ավելի խճճված։
Վերցնենք նախորդ գրախանութի API-ը։ Մի քանի լեզու սպասարկելու համար լեզուն կարելի է ընտրել Language header-ով, այսպես.
Անգլերեն պատասխան.
GET /book-store-api/books?price.currency=USD
-h Language:en
{
"books": [
{
"id":"04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets
to writing pristine, maintainable,
and efficient code that stands the
test of time. Discover essential principles,
patterns, and best practices that
empower you to create software
that is not only functional but also
a joy to read and work with. Take
your programming skills to the next
level with this indispensable guide to
achieving clarity, simplicity, and
excellence in your code."
},
{
"id":"9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide to
mastering the art of pragmatic software
development. Learn how to approach
coding challenges with a practical mindset,
leverage powerful tools, and adopt efficient
techniques that lead to success in any
programming project. Unravel the secrets
of effective team collaboration, debugging,
and problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world advice,
this book is your roadmap to becoming
a truly pragmatic programmer."
}
]
}
Ինտերնացիոնալիզացիան կարող է փոքր բարդացում թվալ, սակայն այն իսկապես դժվարություններ է բերում։ Ինտեգրատորի համար այն կարող է թվալ ընդամենը մեկ լրացուցիչ header՝ լեզուն ընտրելու համար։ API մշակողների համար, սակայն, մեխանիզմի ստեղծումը ուշադիր մտածողություն է պահանջում։ Ինտերնացիոնալիզացիայի կարևոր հետևանքը վերաբերում է ապագա սպասարկմանը. API-ի վերադարձրած ցանկացած նոր լեզվից կախված բովանդակություն պետք է թարգմանվի բոլոր աջակցվող լեզուներով։ Թարգմանությունը կարելի է ավտոմատացնել, սակայն որակն ապահովելու համար անհրաժեշտ են մարդ թարգմանիչներ, ինչը լրացուցիչ ծախսեր է նշանակում API ստեղծող ընկերության համար։ Այն կարող է նաև դանդաղեցնել API-ի մշակումը. մեկ օր պահանջող պարզ խնդիրը թարգմանություններին սպասելու պատճառով կարող է ձգվել մինչև մեկ շաբաթ։
Այդ իսկ պատճառով աջակցվող լեզուները պետք է ընտրել զգույշ և սահմանափակել դրանք ապրանքի տեսանկյունից ամենակարևորներով։ Եվս մեկ լեզու ավելացնելը մշակման ընթացքում կարող է հեշտ թվալ, բայց երկարաժամկետ հեռանկարում կարող է բարձր սպասարկման ծախսեր պարունակել։
Պատասխանատվություն
Ճարտարապետության մեջ պատասխանատվությունը (liability) նշանակում է, որ համակարգը կամ բաղադրիչը պատասխանատու է կոնկրետ վարքագծի, ֆունկցիաների կամ արդյունքների համար։ Դա այն ճարտարապետական բնութագրերից մեկն է, որոնք նպատակ ունեն որոշել՝ ով ինչի տերն է և ինչ պարտավորություններ ունի համակարգի նախագծի յուրաքանչյուր մասը։ API-ների համար պատասխանատվությունը կարող է վերաբերել իրավական պարտավորություններից, սերտիֆիկացումից և API-ի սպեցիֆիկացիաներից բխող պահանջների կատարմանը։
Խնդիրն ավելի հստակ ցույց տալու համար վերադառնանք գրախանութի API-ին և դիտարկենք հետևյալ սցենարը.
Գրախանութը ցանկանում է ընդլայնել վճարման տարբերակները՝ ավելացնելով վճարման նոր եղանակներ, ինչպիսիք են կրիպտոարժույթները (օր.՝ Bitcoin, Ethereum) և թվային դրամապանակները (օր.՝ Apple Pay, Google Pay)։
Այստեղ վճարման նոր եղանակները կարող են API-ին ստիպել համապատասխանել կանոնակարգերին և նկատառումներին, ինչպիսիք են.
- Կրիպտոարժույթների կանոնակարգեր. Քանի որ կրիպտոարժույթները գործում են ապակենտրոնացված ցանցերում, դրանց օգտագործումը ֆինանսական գործարքների համար կարող է ենթարկվել հատուկ կանոնակարգերի։ API-ն ստիպված կլինի համապատասխանել կրիպտոարժույթների վերաբերյալ գործող կանոններին, այդ թվում՝ փողերի լվացման դեմ պայքարի (AML) և հաճախորդին ճանաչելու (KYC) պահանջներին։
- Թվային դրամապանակների կանոնակարգեր. Թվային դրամապանակների դեպքում API-ն կարող է ստիպված լինել հետևել յուրաքանչյուր դրամապանակի մատակարարի սահմանած կանոններին և անվտանգ կերպով մշակել հաճախորդի տվյալները՝ օրինակ վճարային տվյալներն ու անձնական տեղեկությունները։ Դրան գումարած՝ Apple Pay-ն ու Google Wallet-ն ունեն վերադարձի իրենց սեփական ընթացակարգերը, որոնք պետք է մշակվեն զգույշ և ճիշտ։
- Տվյալների պաշտպանության և գաղտնիության օրենքներ. Վճարման նոր եղանակներ ավելացնելուց հետո API-ն պետք է լուծի լրացուցիչ ֆինանսական և անձնական տեղեկությունների մշակման հետ կապված տվյալների պաշտպանության և գաղտնիության ցանկացած հարց։
- Ֆինանսական անվտանգության ստանդարտներ. API-ն պետք է հետևի ոլորտի ստանդարտ անվտանգության պրակտիկաներին՝ զգայուն վճարային տվյալները պաշտպանելու և խարդախությունը կամ չարտոնված մուտքը կանխելու համար։
- Օգտատիրոջ համաձայնություն և պայմանագրեր. Վճարման եղանակից կախված՝ API-ն կարող է ստիպված լինել ստանալ օգտատերերի հստակ համաձայնությունը՝ որոշակի տարբերակներով վճարումներ մշակելու համար և հարգել այդ եղանակների հետ կապված ցանկացած համաձայնագիր կամ ծառայության պայմաններ։
Գրախանութի API-ում վճարման նոր եղանակներ ավելացնելիս կազմակերպությունը պետք է ուշադիր գնահատի և կատարի այս նոր իրավական պարտավորությունները։ Դա կարող է նշանակել API-ի ֆունկցիոնալության, անվտանգության արձանագրությունների և վճարումների մշակման թարմացում, որպեսզի դրանք բավարարեն ընտրված վճարման եղանակների նկատմամբ կիրառվող կանոնակարգերին։ Այս մեխանիզմների մշակման ծախսերից բացի, կարող է անհրաժեշտ լինել նաև իրավաբան մասնագետներ վարձել՝ ամեն ինչի լիարժեք համապատասխանությունն ապահովելու համար։
Արտադրողականություն
API-ի արտադրողականության մասին խոսելիս առաջանում են երկու հիմնական կողմեր. պատասխանի ժամանակը, որը չափում է մեկ հարցման մշակման տևողությունը, և թողունակությունը, որը չափում է, թե ժամանակի տվյալ միավորում API-ն քանի հարցում կարող է սպասարկել։ Արտադրողականությունը կարելի է բարելավել տարբեր մեխանիզմներով, օրինակ՝ pagination-ով, որը մեծ տվյալների հավաքածուները արդյունավետ կերպով ստանում և ներկայացնում է, և սերվերային քեշավորմամբ, որը հաճախ պահանջվող տվյալները պահում է մոտ և նվազեցնում կրկնվող մշակումը։ Նման օպտիմիզացիաների շնորհիվ API-ն կարող է ավելի արագ արձագանքել, ավելի շատ հարցում սպասարկել և օգտատերերին ապահովել ավելի սահուն, ավելի արագ արձագանքող փորձ։
Միևնույն ժամանակ, այս մեխանիզմները կարող են API-ն դարձնել ավելի բարդ։ Տեսնենք, թե ինչպես կարող է սերվերային քեշի ավելացումը բարդացնել Bookstore API-ն։ Վերը ցույց տրված endpoint-ը, որը վերադարձնում է հասանելի գրքերը, լավ թեկնածու է reverse քեշավորման համար, հատկապես երբ գրքերի ցանկը, պաշարը, գներն ու փոխարժեքները հազվադեպ են փոխվում.
Ճիշտ իրականացված սերվերային քեշը պետք է անտեսանելի լինի հաճախորդի համար։ Սակայն վատ արված դեպքում այն կարող է հաճախորդին հնացած պատասխաններ տալ, կամ քեշն ինքը կարող է վնասել API-ի արտադրողականությանը։ Դա կանխելու համար API մատակարարները պետք է մանրակրկիտ մտածեն հնարավոր դժվարությունների և թակարդների մասին, ինչպիսիք են.
- Քեշի անվավերացում. Համոզվել, որ քեշը թարմացվում կամ անվավեր է ճանաչվում անմիջապես, երբ հիմքում ընկած տվյալները փոխվում են, որպեսզի հաճախորդները հնացած կամ սխալ տեղեկություն չստանան։
- Քեշի ժամկետի քաղաքականություններ. Համապատասխան ժամկետային քաղաքականությունների սահմանում, որոնք հավասարակշռում են տվյալների թարմությունն ու քեշի արդյունավետությունը, որպեսզի քեշավորված տվյալները ավելորդ երկար կամ կարճ չապրեն։
- Տվյալների հետևողականություն. Քեշավորված տվյալների հետևողականության պահպանում backend-ի աղբյուրի հետ՝ անհամապատասխանություններից և չհամընկնող տվյալներից խուսափելու համար։
- Քեշի չափ և հիշողության կառավարում. Քեշի չափի և հիշողության օգտագործման վերահսկում՝ ռեսուրսների չափից ավելի սպառումը կանխելու և համակարգի մասշտաբավորելիությունը պահպանելու համար։
- Ազդեցություն արտադրողականության վրա. Քեշավորման մեխանիզմի մանրակրկիտ թեստավորում՝ API-ի արտադրողականության վրա դրա ազդեցությունը չափելու և նոր խոչընդոտներ չստեղծելու համար։
- Անվտանգության նկատառումներ. Զգայուն տվյալների քեշավորման անվտանգության ռիսկերի մշակում՝ համոզվելով, որ զգայուն տեղեկությունը չի պահվում քեշում և մուտքի վերահսկումը ճիշտ է կարգավորված։
Քեշավորման մեխանիզմ ավելացնելու որոշումը ուշադիր մտածողություն է պահանջում, ուստի արժե երկու անգամ մտածել, նախքան առաջ գնալը։
Հետադարձ համատեղելիություն
Գործնականում բոլորը սպասում են, որ API-ները հետադարձ համատեղելի լինեն, բայց դրան հասնելու մի քանի ճանապարհ կա, որոնք հաճախ ներառում են API-ի տարբերակավորում (versioning) իր բազմաթիվ ձևերից մեկով։ Հետադարձ համատեղելիության վերաբերյալ ընտրությունները մեծ ազդեցություն ունեն API-ի բարդացման վրա, ինչը այն դարձնում է լայն թեմա, որը ես ավելի մանրամասն լուսաբանել եմ առանձին հոդվածում.
- Breaking Changes in APIs. այս հոդվածը դիտարկում է տարբերակներ, որոնք նվազեցնում են ետ անհամատեղելի փոփոխությունների հաճախությունը կամ ընդհանրապես վերացնում դրանք՝ դյուրացնելով անցումները API սպառողների համար։
Նույնիսկ հետադարձ համատեղելիության ձգտելիս էական է մնում ողջամիտ որոշումներ կայացնել, որոնք լավագույնս համապատասխանում են API-ի կոնկրետ կիրառման դեպքին։
Դյուրատեղափոխելիություն
API-ի դյուրատեղափոխելիությունը կարևոր բնութագիր է, որը թույլ է տալիս API-ն տեղափոխել տարբեր հարթակներ և համակարգեր և օգտագործել այնտեղ առանց էական փոփոխությունների։ Մի քանի տվյալների ձևաչափերի աջակցումը դյուրատեղափոխելիության մեծ մասն է, քանի որ այն թույլ է տալիս API-ին սպասարկել հաճախորդների ավելի լայն շրջանակ։ Սակայն նկատի ունեցեք, որ մի քանի ձևաչափի աջակցումը կարող է նաև ձեր API-ն դարձնել ավելի բարդ։
Օրինակ վերցնենք Bookstore API-ը և ենթադրենք, որ ուզում ենք աջակցել և՛ JSON, և՛ XML տվյալների ձևաչափերին՝ օգտագործելով բովանդակության բանակցման (content negotiation) մեխանիզմներ։
Գրքերի endpoint-ի պատասխանը JSON-ով
GET /book-store-api/books?price.currency=USD
-h Accept:application/json
{
"books": [
{
"id":"04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets to writing
pristine, maintainable, and efficient code
that stands the test of time. Discover
essential principles, patterns, and best
practices that empower you to create
software that is not only functional but
also a joy to read and work with. Take
your programming skills to the next
level with this indispensable guide
to achieving clarity, simplicity, and
excellence in your code."
},
{
"id":"9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges with
a practical mindset, leverage powerful
tools and adopt efficient techniques
that lead to success in any programming
project. Unravel the secrets of effective
team collaboration, debugging, and
problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world
advice, this book is your roadmap to
becoming a truly pragmatic programmer."
}
]
}
Գրքերի endpoint-ի պատասխանը XML-ով.
GET /book-store-api/books?price.currency=USD
-h Accept:application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<root>
<books>
<id>04b1d68-3a85-4ec0-a4e6-8d7a936d4c02</id>
<title>Clean Code: A Handbook of Agile Software Craftsmanship</title>
<author>Robert C. Martin</author>
<stock>3</stock>
<price>
<amount>15</amount>
<currency>USD</currency>
</price>
<description>Unlock the secrets to
writing pristine, maintainable, and
efficient code that stands the test of
time. Discover essential principles,
patterns, and best practices that
empower you to create software that
is not only functional but also a joy
to read and work with. Take your
programming skills to the next level
with this indispensable guide to achieving
clarity, simplicity, and excellence
in your code.
</description>
</books>
<books>
<id>9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773</id>
<title>The Pragmatic Programmer: Your journey to mastery</title>
<author>David Thomas, Andrew Hunt</author>
<stock>5</stock>
<price>
<amount>17</amount>
<currency>USD</currency>
</price>
<description>Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges
with a practical mindset, leverage
powerful tools, and adopt efficient
techniques that lead to success
in any programming project.
Unravel the secrets of effective
team collaboration, debugging,
and problem-solving to become
a highly skilled and adaptable
developer. Packed with timeless
wisdom and real-world advice,
this book is your roadmap to
becoming a truly pragmatic programmer.
</description>
</books>
</root>
Մի քանի ձևաչափի աջակցումը կարող է բերել մի շարք դժվարությունների.
- API ինտեգրատորները պետք է նշեն, թե ինչ բովանդակության տիպով են ուզում ստանալ տվյալները. եթե չնշեն, կստանան լռելյայն ձևաչափը, եթե այն կարգավորված է։
- Հաճախորդներին անհրաժեշտ է լավ փաստաթղթավորում, որը բացատրում է, թե ինչպես ճիշտ օգտագործել և մշակել տարբեր ձևաչափերը։
- API-ի յուրաքանչյուր փոփոխություն պետք է կիրառվի բոլոր աջակցվող ձևաչափերի վրա՝ դրանց հետևողականությունը պահպանելու և անհամապատասխանություններից խուսափելու համար։
Ինչպես նախորդ դեպքերում, արժե հարցնել՝ արդյոք դյուրատեղափոխելիության պահանջը կատարելը բավարար բիզնես արժեք է տալիս, որպեսզի փոխհատուցի բարդացման հնարավոր աճը։
Անվտանգություն
Անվտանգությունը վեբ API-ների համար պարտադիր է։ Այն սահմանում է կանոնները, որոնցով հաճախորդները կարող են մուտք գործել API-ի տարբեր մասեր, այդ թվում՝ այնպիսի պայմաններ, ինչպիսիք են տրամադրվող մուտքի մակարդակը և այն, թե որքան հաճախ կարող է տվյալ հաճախորդը հարցումներ ուղարկել։ Այս հիմնական կողմը պաշտպանում է API-ի ռեսուրսներն ու վերահսկում դրանց օգտագործումը՝ դարձնելով հաճախորդների և API-ի հնարավորությունների փոխազդեցությունը անվտանգ և կարգավորված։
Հաճախորդներին լիազորելու ամենատարածված եղանակներից մեկը JWT-ի (JSON Web Token) օգտագործումն է OAuth 2.0 նման մեխանիզմների հետ միասին։ JWT-ն տալիս է կողմերի միջև լիազորման տեղեկություն փոխանցելու կոմպակտ, ինքնաբավ եղանակ, ինչը այն դարձնում է API փոխազդեցությունների անվտանգության հանրաճանաչ տարբերակ։ OAuth 2.0-ն, իր հերթին, առաջարկում է ստանդարտացված լիազորման ֆրեյմվորք, որը թույլ է տալիս մուտքի իրավունքները անվտանգ կերպով փոխանցել հաճախորդներին՝ առանց զգայուն հավատարմագրերը բացահայտելու։ Համակցված այս տեխնոլոգիաները տալիս են ամուր հիմք API-ի ռեսուրսները պաշտպանելու համար՝ միաժամանակ դյուրացնելով լիազորված հաճախորդներին վերահսկվող մուտք տրամադրելը։
Այդուհանդերձ, JWT-ի և OAuth 2.0-ի իրականացումը բերում է մի շարք դժվարություններ և նկատառումներ, որոնք պետք է զգույշ մշակվեն անվտանգությունն ամբողջական և արդյունավետ պահելու համար, օրինակ.
- Token-ի վավերականություն և ժամկետ. Token-ների կյանքի տևողության և թարմացումների ճիշտ կառավարում։
- Token-ի չեղարկում. Վտանգված կամ կորած token-ների արագ անվավեր ճանաչում։
- Token-ի scope. Մուտքի իրավունքների ճշգրիտ նշում և կառավարում։
- Token-ի պահպանում և փոխանցում. Token-ների անվտանգ պահում և ուղարկում։
- Authorization Code Flow. Այս բազմաքայլ հոսքի ճիշտ իրականացում և շահագործում։
- Token-ի արտահոսք և անձի կեղծում. Չարտոնված մուտքի և տվյալների արտահոսքերի կանխում։
- Token-ների կառավարում և աուդիտ. Հետևել, թե ինչպես են token-ներն օգտագործվում և ինչ է կատարվում դրանց հետ։
Լիազորումը գրեթե միշտ անխուսափելի է, բայց կան իրավիճակներ, երբ այն կարելի է բաց թողնել։ Օրինակ, երբ կառուցվում է ներքին MVP, որտեղ անվտանգությունն ավելի քիչ կարևոր է, մանրակրկիտ լիազորումը հանելը կարող է արագացնել MVP-ի մատակարարումը՝ առանց խաթարելու դրա նպատակը։
API-ի վատ կառուցվածք
Նույնիսկ ֆունկցիոնալ և ոչ ֆունկցիոնալ նվազագույն պահանջների դեպքում API-ն կարող է չափից ավելի բարդանալ, եթե դրա կառուցվածքն անարդյունավետ է։ Այս մասում դիտարկվում են այն սկզբունքներն ու փոխզիջումները, որոնք օգնում են կոնկրետ կիրառման դեպքի համար ձևավորել լավագույն API կառուցվածքը։
API-ի համակցվածություն
Քանի որ API-ն բաղադրիչի մուտքի կետն է, Ռոբերտ Մարտինի «Clean Architecture» գրքում նկարագրված բաղադրիչների համակցվածության սկզբունքները հավասարապես կիրառելի են API-ի նախագծման վրա։ API-ի համատեքստ թարգմանված՝ այս կանոններն ունեն հետևյալ տեսքը.
- REP (Release Equivalence Principle). API-ում ներառեք այն տարրերը, որոնք թողարկվում են միասին՝ որպես մեկ միավոր, և խուսափեք մի քանի API-ի՝ նույն տարբերակի համար ունենալուց
- CCP (Common Closure Principle). API-ում խմբավորեք այն տարրերը, որոնք փոխվում են նույն պատճառներով և նույն ժամանակ։
- CRP (Common Reuse Principle). API-ում ներառեք միայն այն ֆունկցիոնալությունը, որը API ինտեգրատորները սովորաբար վերաօգտագործում են։
Ինչպես նշում է գիրքը, այս սկզբունքները «հակված են պայքարել միմյանց դեմ», ուստի դրանք պետք է զգույշ հավասարակշռել։ Գրքի դիագրամը API-ների վրա նախագծելիս բացահայտվում են հետևյալ փոխզիջումները.
REP-ի անտեսում (ցավոտ ինտեգրացիա). Ինտեգրատորները կարող են վատ փորձ ունենալ, քանի որ ստիպված են ինտեգրվել բազմաթիվ API-ների հետ։ Այդ դեպքում նրանք պետք է համոզվեն, որ այդ API-ները համատեղելի են միմյանց հետ, ինչը նրանց աշխատանքը դարձնում է ավելի բարդ և ծախսատար։
CCP-ի անտեսում (ցավոտ մշակում). Մշակումը կարող է դառնալ ծանրաշարժ։ Այս սկզբունքի անտեսումը սովորաբար մատնանշում է մի քանի API-ների խիստ կապակցվածություն, ինչը կարող է լրջորեն դանդաղեցնել API-ն։ Այդ կապակցվածության պատճառով այդ API-ների վրա աշխատանքը պետք է ուշադիր համակարգվի, ինչը բերում է բարդություններ և դժվարություններ։
CRP-ի անտեսում (ցավոտ թողարկումներ). Այս սկզբունքի անտեսումը հաճախ թողնում է մեզ մի քանի թիմերի ստեղծած ծանրաշարժ API-ի հետ։ Սա սովորաբար նշանակում է երկար թողարկման ցիկլեր և փոփոխությունների լայն շրջանակ, ինչը մեծացնում է ձախողումներ ներմուծելու ռիսկը։
Endpoint-ների մանրամասնություն
Մեկ այլ կարևոր հարց, որ պետք է տալ.
Քանի՞ endpoint կա, և դրանցից յուրաքանչյուրը որքանո՞վ է ծածկում։
Պարզ պատասխանը. endpoint-ը պետք է ներառի հաճախորդի կարիքները բավարարելու համար անհրաժեշտ ամբողջ տվյալը՝ և ոչ ավելին։
Բայց միշտ հնարավո՞ր է դրան հասնել։
Երբ կան տարբեր կարիքներով մի քանի հաճախորդներ, այս հավասարակշռությունը կարող է դժվար լինել։ Իրականում կարևոր է իմանալ, թե ինչ է տեղի ունենում, երբ endpoint-ները չափազանց լայն են կամ չափազանց նեղ։
Վերադառնանք, օրինակ, Bookstore API-ին և դրա ֆունկցիոնալությանը, որը վերադարձնում է տեղեկություն հեղինակների և նրանց հասանելի գրքերի մասին։ Այն իրականացնելու մի եղանակ է ստեղծել endpoint, որը վերադարձնում է գրքերի, հեղինակների և նրանց աշխատանքների մասին ամբողջ տվյալը.
{
"authors": [
{
"id": "704b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"name": "Robert C. Martin",
"availableBooks": [
{
"id": "c1bdc5c6-7a49-4c45-8e3c-2f47e65a0375",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets
to writing pristine, maintainable, and
efficient code that stands the test of time.
Discover essential principles, patterns,
and best practices that empower you
to create software that is not only functional
but also a joy to read and work with.
Take your programming skills to the
next level with this indispensable
guide to achieving clarity, simplicity,
and excellence in your code."
},
{
"id": "e8c8a24b-5792-4d16-87d5-9e3c8e0b43e8",
"title": "Clean Architecture: A Craftsman Guide to Software Structure and Design",
"stock": 2,
"price": {
"amount": 20,
"currency": "USD"
},
"description": "Design Software Systems
for Maximum Maintainability and Flexibility.
Explore the principles and patterns
behind building clean, robust, and adaptable
software architectures, guided by industry
expert Robert C. Martin. Uncover the secrets
to crafting systems that stand the test of time,
fostering a deep understanding of architecture
design that empowers developers to create
software that is as elegant as it is efficient."
}
]
},
{
"id": "9b5f0b3e-820d-45c7-9847-eb3e3b33ab8f",
"name": "David Thomas",
"availableBooks": [
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges with
a practical mindset, leverage powerful
tools, and adopt efficient techniques
that lead to success in any programming
project. Unravel the secrets of
effective team collaboration, debugging,
and problem-solving to become
a highly skilled and adaptable developer.
Packed with timeless wisdom and real-world
advice, this book is your roadmap to
becoming a truly pragmatic programmer."
}
]
},
{
"id": "ccd61b63-9449-4186-b6f3-ae0fbc3d038a",
"name": "Andrew Hunt",
"availableBooks": [
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how to
approach coding challenges with a
practical mindset, leverage powerful tools,
and adopt efficient techniques that
lead to success in any programming project.
Unravel the secrets of effective team
collaboration, debugging, and problem-solving
to become a highly skilled and adaptable
developer. Packed with timeless wisdom
and real-world advice, this book is your
roadmap to becoming a truly pragmatic
programmer."
}
]
}
]
}
Մեկ այլ տարբերակ է HATEOAS մոտեցման օգտագործումը.
{
"authors": [
{
"id": "704b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"name": "Robert C. Martin",
"availableBooks": [
"/book-store-api/books/c1bdc5c6-7a49-4c45-8e3c-2f47e65a0375",
"/book-store-api/books/e8c8a24b-5792-4d16-87d5-9e3c8e0b43e8"
]
},
{
"id": "9b5f0b3e-820d-45c7-9847-eb3e3b33ab8f",
"name": "David Thomas",
"availableBooks": [
"/book-store-api/books/9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773"
]
},
{
"id": "ccd61b63-9449-4186-b6f3-ae0fbc3d038a",
"name": "Andrew Hunt",
"availableBooks": [
"/book-store-api/books/9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773"
]
}
]
}
Թե որ մոտեցումն է ավելի լավ, կախված է համատեքստից։ Առաջինը տալիս է ամբողջական կառուցվածք, ուստի անհրաժեշտ ամեն ինչ ստանալու համար կարող է բավարար լինել մեկ API կանչը։ Դրա գինը պատասխանի ավելի մեծ ծավալն ու ավելի բարդ փաստաթղթավորումն է։ Երկրորդը կառուցվածքը պահում է ավելի պարզ, բայց նույնիսկ հիմնական խնդիրները, օրինակ՝ հեղինակների ցանկը՝ նրանց գրքերի վերնագրերի հետ միասին, կարող են մի քանի API կանչ պահանջել։ Ընտրությունը կախված է այնպիսի բաներից, ինչպիսիք են տվյալների բարդությունը, ցանցային կողմերը և այն օգտատիրոջ փորձը, որը ցանկանում եք տրամադրել։
Այս օրինակը ցույց է տալիս, որ չկա մեկ ճիշտ պատասխան այն հարցի, թե որքան մեծ պետք է լինի տվյալ endpoint-ը։ Endpoint-ներ նախագծելիս, սակայն, խելամիտ է հիշել այս փոխզիջումը.
- Եթե ձեր endpoint-ները չափազանց փոքր են, API հաճախորդներին անհրաժեշտ կլինեն բազմաթիվ API կանչեր՝ իրենց պետք եղածը ստանալու համար, ինչը ինտեգրացիան դարձնում է ավելի բարդ։
- Եթե ձեր endpoint-ը չափազանց մեծանում է, մեծ payload-ը կարող է հանգեցնել պատասխանի երկար ժամանակի, և այդպիսի բարդ endpoint-ը կարող է դժվար լինել փաստաթղթավորել և օգտագործել։
Ամփոփում
Այս հոդվածում քննարկվեց, թե ինչ է API-ի բարդացումը և ինչու է այն ուշադրության արժանի։ Մենք դիտարկեցինք խնդիրները, որոնք կարող են առաջացնել բարդ API-ները, և այն գործոնները, որոնք ազդում են API-ի բարդության վրա, ինչպիսիք են ֆունկցիոնալ և ոչ ֆունկցիոնալ պահանջները և API-ի անարդյունավետ նախագծումը։ Ինչպես տեսանք, բարդությունը միշտ չէ, որ հնարավոր է ամբողջությամբ խուսափել, բայց շատ դեպքերում այն նվազեցնելու եղանակներ կան։
TL;DR
- Ձեր API-ի պարզությունը կարող է ազդել այն բանի վրա, թե որքան լայն կընդունվի։
- API-ի բարդության աղբյուրները սովորաբար ընկնում են այնպիսի խմբերի մեջ, ինչպիսիք են ֆունկցիոնալ պահանջները, ոչ ֆունկցիոնալ պահանջները և API-ի վատ կառուցվածքը։
- Ընտրեք ձեր API-ի ֆունկցիոնալությունը զգուշորեն։
- Սահմանափակեք ոչ ֆունկցիոնալ պահանջները միայն իսկապես անհրաժեշտներով։
- Հոգ տարեք ձեր API-ի կառուցվածքի մասին՝ հաշվի առնելով API-ի համակցվածությունը և endpoint-ների մանրամասնությունը։