Ի՞նչ է API-ն։ Պարզ ուղեցույց app builder-ների համար
API-ն (application programming interface) ծրագրային ապահովման մի մասի համար սահմանված ձև է, որով այն մյուսից տվյալ է խնդրում կամ որևէ բան անել է տալիս։ Ձեր հավելվածը համաձայնեցված ձևաչափով հարցում է ուղարկում՝ «տուր վաղվա ամրագրումները», «գանձիր այս քարտից 20 եվրո», «ամփոփիր այս տեքստը», և մյուս համակարգը կառուցվածքային պատասխան է վերադարձնում։ API-ները այն միջոցն են, որով հավելվածի մասերը խոսում են միմյանց հետ, և որով ձեր հավելվածը օգտագործում է արտաքին ծառայություններ՝ վճարումներ, էլ. նամակ, քարտեզներ և AI։
Ինչու են API-ները կարևոր AI-ով կառուցելիս
Գրեթե յուրաքանչյուր օգտակար հավելված բաղկացած է մասերից, որոնք հաղորդակցվում են API-ների միջոցով․
- Հավելվածի ներսում բրաուզերի էկրանները կանչում են ձեր սեփական backend-ի API-ն՝ տվյալները բեռնելու և պահելու համար։
- Հավելվածից դուրս ձեր backend-ը կանչում է այլ ընկերությունների API-ները․ Stripe-ը՝ վճարումներ ընդունելու, էլ. նամակի մատակարարը՝ անդորրագրեր ուղարկելու, AI մոդելի մատակարարը՝ տեքստ գեներացնելու համար։
Երբ AI builder-ին խնդրում եք «ընդունել վճարումներ» կամ «ավելացնել AI ամփոփում», նա իրականում գրում է կոդ, որը կանչում է API։ Հիմունքները իմանալը օգնում է հասկանալ, թե ինչ է անհրաժեշտ AI-ին ձեր կողմից (սովորաբար՝ այդ ծառայության հաշիվ և API բանալի), որտեղ կարող են սխալ լինել և ինչ արժեն դրանք։
Ամենօրյա անալոգիա
Մտածեք ռեստորանի մասին։ Դուք չեք մտնում խոհանոց և չեք եփում։ Կարդում եք մենյուն, ասում եք մատուցողին ձեր ուզածը այնպես, որ խոհանոցը հասկանա, և մատուցողը բերում է ձեր ուտելիքը, կամ ասում է, որ ուտեստը սպառվել է։
- Մենյուն API փաստաթղթերն են՝ թվարկում են, թե ինչ կարելի է խնդրել և ինչպես։
- Մատուցողը API-ն է՝ համաձայնեցված մեկ ձևը, որով հարցումները մտնում են և պատասխանները դուրս են գալիս։
- Խոհանոցը մյուս համակարգն է․ ներսում ինչպես է աշխատում, պետք չէ իմանաք։
- Ձեր պատվերը հարցումն է, ափսեն պատասխանը։
Խոհանոցը կարող է փոխել իր վառարանները և աշխատակիցներին, առանց ձեզ ազդելու, քանի դեռ մենյուն նույնն է մնում։ Ահա API-ի իրական արժեքը․ այն թույլ է տալիս երկու համակարգերի աշխատել միասին, առանց որևէ մեկին իմանալու, թե մյուսն ինչպես է կառուցված։
Ինչպես է աշխատում վեբ API հարցումը
Ամենից շատ հանդիպող API-ները վեբ API-ներ են, որոնք աշխատում են HTTP-ով՝ նույն protocol-ով, որն օգտագործում է ձեր բրաուզերը։ Յուրաքանչյուր հարցում ունի մի քանի մաս․
| Մաս | Ինչ է | Օրինակ |
|---|---|---|
| Մեթոդ | Գործողության տեսակը | GET (կարդալ), POST (ստեղծել) |
| URL / endpoint | Այն բանի հասցեն, որի հետ աշխատում եք | https://api.example.com/bookings |
| Վերնագրեր (headers) | Լրացուցիչ տեղեկություն, ներառյալ թե դուք ով եք | Authorization: Bearer <your key> |
| Մարմին (body) | Ուղարկվող տվյալները՝ ստեղծման և թարմացման համար | {"name": "Lena", "time": "14:00"} |
Եվ յուրաքանչյուր պատասխան ունի․
| Մաս | Ինչ է | Օրինակ |
|---|---|---|
| Կարգավիճակի կոդ | Թիվ, որը ցույց է տալիս, թե ինչպես անցավ | 200 OK, 201 Created, 404 Not Found |
| Մարմին | Վերադարձված տվյալները, սովորաբար JSON-ով | {"id": 5001, "status": "confirmed"} |
JSON-ը (JavaScript Object Notation) անունների և արժեքների պարզ տեքստային ձևաչափ է՝ փակագծերի մեջ։ Այն վեբ API-ների տվյալներ փոխանակելու ստանդարտ միջոցն է։
REST՝ ամենատարածված ոճը
REST-ը վեբ API-ներ նախագծելու լայնորեն կիրառվող կոնվենցիա է։ Յուրաքանչյուր տեսակի բան ունի իր URL-ը, իսկ ստանդարտ մեթոդները ասում են, թե ինչ եք անում դրա հետ։ Ահա, թե ինչ տեսք կարող է ունենալ REST API-ը ամրագրումների հավելվածի համար․
| Մեթոդ | Endpoint | Ինչ է անում |
|---|---|---|
GET | /api/bookings | Թվարկել ամրագրումները |
GET | /api/bookings/5001 | Ստանալ մեկ ամրագրում |
POST | /api/bookings | Ստեղծել նոր ամրագրում |
PATCH | /api/bookings/5001 | Փոխել ամրագրման մասը, օրինակ՝ ժամը |
DELETE | /api/bookings/5001 | Չեղարկել (ջնջել) ամրագրումը |
PUT-ն էլ կա և սովորաբար փոխարինում է ամբողջ գրառումը, մինչդեռ PATCH-ը փոխում է միայն ուղարկած դաշտերը։
Ամենից հաճախ տեսնվող կարգավիճակի կոդերը՝
| Կոդ | Նշանակություն |
|---|---|
200 / 201 | Հաջողություն / ստեղծված |
400 | Վատ հարցում․ ուղարկածի մեջ ինչ-որ բան սխալ էր կամ բացակայում էր |
401 | Նույնականացված չէ․ վավեր մուտք կամ բանալի չկա |
403 | Արգելված․ ճանաչված եք, բայց այս բանը անելու թույլտվություն չունեք |
404 | Չի գտնվել |
429 | Չափից շատ հարցումներ․ հասել եք սահմանաչափին |
500 | Սերվերում սխալ է եղել |
Երբ ձեր հավելվածը կոտրվում է, կարգավիճակի կոդը հաճախ ամենաարագ նշանն է։ 401 վճարման մատակարարից սովորաբար նշանակում է, որ API բանալին բացակայում է կամ սխալ է, իսկ 429-ը նշանակում է, որ շատ հաճախ եք կանչում։
REST-ը միակ ոճը չէ․ գոյություն ունեն նաև GraphQL և RPC ոճի API-ներ, բայց REST-ն այն է, ինչ օգտագործում են մեծ մասը ծառայությունների և AI-ով կառուցված backend-ները։
Աշխատած օրինակ՝ ամրագրման հաստատում
Երբ հաճախորդը սրահում սանրվածք է ամրագրում, մի քանի API կանչ կարող է տեղի ունենալ մեկ-երկու վայրկյանում․
- Բրաուզերի ամրագրման էջը ուղարկում է
POST /api/bookingsձեր backend-ին՝ ծառայությամբ, ժամով և հաճախորդի տվյալներով։ - Ձեր backend-ը ստուգում է, որ ժամը ազատ է, պահում է ամրագրումը տվյալների բազայում և վերադարձնում
201 Created։ - Ձեր backend-ը կանչում է էլ. նամակի մատակարարի API-ն իր գաղտնի բանալիով՝ «ուղարկիր այս հաստատումը lena@example.com»։
- Եթե կա կանխավճար, ձեր backend-ը խնդրում է վճարման մատակարարի API-ին ստեղծել checkout session և ուղարկում է հաճախորդին այնտեղ։
- Հետագայում վճարման մատակարարը կանչում է ձեր հավելվածը՝ ասելու, որ վճարումը հաջողվել է։ Այդ հակադարձ կանչը webhook է։
Առաջին երկու քայլերը ձեր սեփական API-ն են frontend-ի և backend-ի միջև։ Երրորդից հինգերորդ քայլերը երրորդ կողմի API-ներ են։
Հիմնական տերմինների բացատրություն
| Տերմին | Նշանակություն |
|---|---|
| Endpoint | Մեկ կոնկրետ URL, որին API-ն պատասխանում է։ |
| API բանալի | Գաղտնի տող, որը ձեր հավելվածը ճանաչում է ծառայության համար։ Վարվեք դրա հետ որպես գաղտնաբառի։ |
| Նույնականացում (authentication) | Ապացուցել, թե ով է կանչում՝ բանալիով, թոքենով կամ մուտքով։ Տե՛ս ինչ է նույնականացումը։ |
| Սահմանաչափ (rate limit) | Սահմանափակում, թե որքան հարցում կարող եք անել որոշակի ժամանակահատվածում։ |
| SDK | Պատրաստի կոդի գրադարան, որը հեշտացնում է որոշակի API-ի կանչը։ |
| Փաստաթղթեր (documentation) | «Մենյուն»․ ո՛ր endpoint-ներն են գոյություն ունենում, ինչ են ընդունում և վերադարձնում։ |
| Sandbox / թեստային ռեժիմ | Ծառայության տարբերակ՝ փորձարկելու համար՝ առանց իրական փողի կամ իրական տվյալների։ |
| Webhook | Մյուս ծառայության կանչ ձեր հավելված, երբ ինչ-որ բան է տեղի ունենում։ |
Սովորական սխալներ և թյուրըմբռնումներ
- Գաղտնի բանալիները frontend-ում դնելը։ Ցանկացած բան, որը գտնվում է բրաուզերում աշխատող կոդում, կարող է տեսնել ցանկացած այցելու։ Գաղտնի բանալիները պետք է մնան սերվերում՝ միջավայրի փոփոխականներում կամ գաղտնիքներում։
- Բանալիները չատում կպցնելը։ Չաթի պատմությունը կարող է պահվել։ Օգտագործեք ձեր builder-ի գաղտնիքների գործառույթը, և փոխեք (rotate) յուրաքանչյուր բանալի, որը բացահայտվել է։
- Ենթադրելը, որ API-ն անվճար է։ Շատ API-ներ գանձում են յուրաքանչյուր հարցումի կամ օգտագործման միավորի համար․ AI մոդելների API-ները գանձում են տոկեններով։ Ստուգեք գները և դրեք ծախսերի սահմաններ։ Տե՛ս ինչպես օգտագործել LLM API-ները։
- Խափանումները չմշակելը։ Արտաքին ծառայությունները խափանվում են, ժամանակը սպառվում և հասնում են սահմանաչափերի։ Խնդրեք պատշաճ սխալի հաղորդագրություններ և կրկնվող փորձեր։
- Բրաուզերին կույր վստահելը։ Ձեր սեփական API-ն պետք է ինքը ստուգի թույլտվությունները։ Կոճակը թաքցնելը չի կանգնեցնում որևէ մեկին, ով ուղղակիորեն կանչում է endpoint-ը։
- Թեստավորելիս կենդանի բանալիներ օգտագործելը։ Օգտագործեք թեստային ռեժիմի բանալիներ, մինչև պատրաստ լինեք գործարկմանը։
Ինչ խնդրել ձեր AI builder-ից
- «Ո՞ր արտաքին API-ներն է օգտագործում այս հավելվածը, և յուրաքանչյուրն ինչ է արժում։»
- «Վճարման API-ին կանչիր միայն սերվերից։ Բանալին կարդա միջավայրի փոփոխականից։»
- «Թվարկիր մեր API-ի յուրաքանչյուր endpoint-ը, ինչ է անում և ով է իրավասու կանչել այն։»
- «Սերվերում ստուգիր, որ մուտք գործած օգտատերը տիրապետում է ամրագրմանը, նախքան այն թարմացնելը կամ ջնջելը։»
- «Եթե էլ. նամակի API-ն ձախողվի, միևնույն է պահիր ամրագրումը և գրանցիր սխալը։»
- «Առայժմ օգտագործիր մատակարարի թեստային ռեժիմը։»
API-ները Mythex-ում
Mythex-ը կարող է կառուցել ձեր սեփական API-ն՝ որպես վեբ հավելվածի մաս, կամ որպես առանձին backend Node, Python (FastAPI), C# կամ Java լեզուներով, որը աշխատում է ձեր frontend-ի կողքին, և գրել այն կոդը, որը կանչում է արտաքին ծառայություններ։ Դուք ավելացնում եք նրանց բանալիները որպես նախագծի գաղտնիքներ և ոչ թե չաթում, և դրանք հասանելի են ձեր հավելվածին՝ նախադիտման ժամանակ և հրապարակելուց հետո։ Փաստաթղթերը ունեն ռեցեպտներ ցանկացած API-ի ինտեգրման և REST API backend կառուցելու համար։
Հարցեր
Պարզ ասած, ի՞նչ է API-ն։
API-ն (application programming interface) ծրագրային ապահովման մի մասի համար սահմանված ձև է, որով այն մյուսից տվյալ է խնդրում կամ որևէ բան անել է տալիս։ Ձեր հավելվածը համաձայնեցված ձևաչափով հարցում է ուղարկում, իսկ մյուս համակարգը պատասխան է վերադարձնում՝ օրինակ՝ եղանակի տվյալներ, վճարման արդյունք կամ AI-ի կողմից գեներացված պատասխան։
Ի՞նչ է REST API-ն։
REST API-ն վեբ API-ների տարածված ոճ է, որտեղ յուրաքանչյուր տեսակի բան (ամրագրումներ, հաճախորդներ) ունի URL, և օգտագործում եք ստանդարտ HTTP մեթոդներ՝ GET՝ կարդալու, POST՝ ստեղծելու, PUT կամ PATCH՝ թարմացնելու, DELETE՝ հեռացնելու համար։ Տվյալները սովորաբար վերադառնում են JSON ձևաչափով։
Ի՞նչ է API բանալին և որտե՞ղ պետք է այն պահել։
API բանալին գաղտնի տող է, որը ձեր հավելվածին ճանաչում է ծառայության համար և հաճախ թույլ է տալիս նրան գումար ծախսել կամ մուտք ունենալ տվյալների։ Պահեք այն միջավայրի փոփոխականներում կամ ձեր նախագծի գաղտնիքներում սերվերի վրա, երբեք այն կոդում, որը աշխատում է բրաուզերում, և երբեք հանրային repository-ում։
Ո՞րն է տարբերությունը API-ի և webhook-ի միջև։
API-ի դեպքում ձեր հավելվածը մյուս ծառայությունից որևէ բան է խնդրում, երբ ուզում է։ Webhook-ի դեպքում մյուս ծառայությունը կանչում է ձեր հավելվածը, երբ ինչ-որ բան է տեղի ունենում․ օրինակ՝ վճարման մատակարարը ձեզ տեղեկացնում է, որ վճարումը հաջողվել է։