Ինչպես է այն աշխատում
Ծառայարկման API
Ինչպես է վճարային համակարգը ստեղծում, կասեցնում, սակագինը փոխում և ջնջում հոսթինգի հաշիվներն առանց մարդու մասնակցության, և ինչպես է ինտեգրումն նույնականացվում։
Maran-ը ստեղծված է հոսթինգ վաճառելու համար, ուստի վճարներ ընդունող համակարգը պետք է կարողանա վահանակը կառավարել ինքնուրույն։ Եթե վահանակը կարելի է կառավարել միայն ձեռքով, ապա ամեն ինչ կախված է այն մարդուց, ով նստած է դրա առաջ։
Առայժմ՝ մուտք, ոչ թե բանալի
Վճարային համակարգն այսօր նույնականացվում է որպես մուտք․ այն մտնում է POST /api/v1/auth/login-ով
և ստացված հասանելիության թոքենն ուղարկում է որպես bearer թոքեն։ Թոքենը կարճ ժամանակով է գործում
(լռելյայն՝ 15 րոպե) և թարմացվում է POST /api/v1/auth/refresh-ով։ Ստորև նկարագրված հաշվի կյանքի
ցիկլը պահանջում է ադմինիստրատորի մուտք, ուստի ինտեգրմանը տվեք առանձին մուտք, ոչ թե մարդու մուտքը։
Այդպես նրա նիստերը կարելի է ավարտել առանձին, իսկ նրա կանչերը աուդիտի մատյանում երևում են առանձին։
Սահմանափակ իրավունքներով API բանալիները, որոնցով կարելի կլիներ հաշիվներ ստեղծել՝ ուրիշ ոչինչ չարած, դեռ պատրաստ չեն։ Մինչև դրանց հայտնվելը ինտեգրման մուտքն ունի ադմինիստրատորի բոլոր իրավունքները, իսկ նրա ամեն կանչ գրանցվում է աուդիտի մատյանում՝ մարդու արած գործողությունների կողքին։
Հաշվի կյանքի ցիկլը
| Կանչ | Ինչ է տեղի ունենում սերվերի վրա |
|---|---|
| Ստեղծել | Ստեղծում է համակարգային օգտատիրոջը, նրա տունը և սակագնի քվոտան, ապա գրանցում հաշիվը |
| Կասեցնել | Կանգնեցնում է կայքերն ու մուտքերը, իսկ մնացած ամեն ինչը պահում է․ սա կասեցում է, ոչ թե ջնջում |
| Փոխել սակագինը | Տեղափոխում է քվոտան, աշխատողների բյուջեն և սահմանաչափերը նոր սակագնին |
| Ջնջել | Հեռացնում է բազաները, մուտքերը և jail-ը, ավարտում է հաշվի պրոցեսները, ապա հեռացնում օգտատիրոջը, որպեսզի ոչինչ անտեր չմնա |
Կանչերն են՝ POST /api/v1/accounts, POST /api/v1/accounts/{id}/suspend (և /reactivate),
PUT /api/v1/accounts/{id}/plan և DELETE /api/v1/accounts/{id}։ Դրանցից յուրաքանչյուրը կատարում է նույն գործողությունը, ինչ վահանակի էկրանները։ Ծրագրերի համար
առանձին, ավելի թույլ ուղի չկա․ API-ն և ինտերֆեյսը կանչում են նույն կոդը, ուստի նրանք չեն կարող
տարբեր կերպ հասկանալ, թե ինչ է նշանակում կասեցումը։
Սակագնի հնարավորություններ, հաշիվներ և դիտումներ
Սակագին ստեղծելիս կամ թարմացնելիս պետք է փոխանցել features ցուցակը, այսինքն սակագնով վաճառվող բոլոր հնարավորությունները։ Թարմացնելիս այն ամբողջությամբ փոխարինում է նախկին ցուցակը։ Դատարկ ցուցակը նշանակում է, որ սակագինը ոչ մի հնարավորություն չի տալիս, իսկ առանց ցուցակի հարցումը մերժվում է։ GET /api/v1/plans/features-ը վերադարձնում է հասանելի հնարավորությունները (ադմինիստրատոր)։
Մի քանի վերջնակետ սպասարկում է հենց վահանակի էկրանները։ Դրանք այստեղ նշված են ամբողջականության համար։
| Վերջնակետ | Ով | Նպատակը |
|---|---|---|
GET /api/v1/dashboard/attention-count | Ադմինիստրատոր | Քանի բան է ուշադրություն պահանջում |
GET /api/v1/servers | Ադմինիստրատոր | Կառավարվող սերվերները․ մեկ գրառում՝ local տեսակով |
GET /api/v1/me/accounts | Հաճախորդ | Մուտքին պատկանող հաշիվները |
POST /api/v1/me/active-account | Հաճախորդ | Փոխել ընթացիկ հաշիվը, մարմինը {accountId} |
GET, POST, DELETE /api/v1/me/pinned-pages | Մուտք գործած | Կարդալ, ավելացնել և հեռացնել ընտրյալ էջերը |
/api/v1/me/sub-users | Հաշվի սեփականատեր | Հրավիրել, փոխել և հեռացնել թիմի անդամներին |
POST, GET, DELETE /api/v1/view-as | Ադմինիստրատոր | Սկսել, կարդալ և ավարտել հաշվի դիտումը |
Պատասխաններ առանց մարմնի
Եթե փոփոխությունից հետո ասելու ոչինչ չկա, սերվերը պատասխանում է 204 No Content՝ առանց մարմնի։
Նախկինում այդ դեպքում վերադարձվում էր 200 և true մարմինը, որն ավելին չէր ասում, քան արդեն ասում էր
կարգավիճակի կոդը։ Մարմինը վերլուծող հաճախորդը պետք է դադարի դա անել, իսկ հաջողությունը ստուգող
հաճախորդը պետք է ընդունի ցանկացած 2xx։ Սա վերաբերում է՝
- ինքնությանը՝ ելք, գաղտնաբառի փոփոխություն, նիստերի չեղարկում, հրավերներ, ենթաօգտատերեր, անվտանգության քաղաքականություն և հաշվի դիտման ավարտ,
- սակագներին և պահուստներին՝ ջնջում,
- cron-ին՝ թարմացում, միացում կամ անջատում, ջնջում և միջավայր,
- տվյալների բազաներին, կայքերին և հավաստագրերին՝ ջնջում և հեռացում,
- firewall-ին՝ թույլատրում, մերժում, արգելափակում, արգելքի հանում և սպիտակ ցուցակից հեռացում,
- FTPS և SFTP մուտքերին՝ ջնջում,
- ելքային փոստին՝ պահպանում և փորձնական նամակի ուղարկում,
- մատյանի մակարդակին։
Վերանվանված պատասխանի դաշտեր
Այն դաշտերը, որոնք «այո» կամ «ոչ» էին ասում մի բանի մասին, որը կարող է նաև անհայտ լինել, այժմ անվանում են բոլոր հնարավոր դեպքերը։
| Որտեղ | Դաշտ | Արժեքներ |
|---|---|---|
| Հաշվի սկավառակի օգտագործում | backing | enforced, notEnforced, unmeasured |
| PHP տարբերակներ | defaultStatus | default, notDefault, unknown |
| Մոդուլներ | state | enabled, locked |
| Վահանակ (dashboard) | audience | administrator, customer |
| FTPS սերվեր | tlsEnforcement | enforced, notEnforced, notObserved |
Առողջության հաշվետվության մեջ այլևս ընդհանուր status դաշտ չկա․ փոխարենը կարդացեք
գործակալի և տվյալների բազայի գրառումները։
Ինչի համար այն չէ
Սա սերվերի վրա հրամաններ կատարելու եղանակ չէ։ API-ից գործակալին հասնում է միայն այն, ինչ գործակալն արդեն ընդունում է որպես տիպավորված գործողություն, և այդ գործողությունների փակ ցանկը նույնն է, որով սահմանափակված է հենց վահանակը։ Կանչողը shell խնդրել չի կարող, որովհետև մյուս կողմում այն տրամադրող ոչինչ չկա։
Սխալներն ասում են միայն այն, ինչ կանչողը իրավունք ունի իմանալ
Այն հաշվի ռեսուրսը, որի անունից կանչողը չի գործում, պատասխանում է չի գտնվել, ոչ թե արգելված։ «Արգելված է» պատասխանը կհաստատեր, որ ռեսուրսը գոյություն ունի, իսկ այդ փաստը կանչողը չպետք է իմանա։
Նույն բազան երկրորդ անգամ ստեղծելիս սերվերը հայտնում է, որ այն արդեն կա, և առաջին գաղտնաբառը շարունակում է աշխատել։ Եթե պատասխանը կորել է, կրկնված հարցումը չպետք է զրոյացնի այն տվյալները, որոնք հաճախորդին արդեն մեկ անգամ ցույց են տվել։ Սա այն մանրուքներից է, որոնք երևում են միայն իրական միջավայրում և միայն ուրիշի հաճախորդի վրա։
Եթե վերջնակետը մուտքի կանոն չի նշել, հաճախորդների համար այն փակ է, ոչ թե բաց։ Անանուն կանչողը մերժվում է 401-ով, մուտք գործած հաճախորդը՝ 403-ով և դատարկ մարմնով, իսկ թույլատրվում է միայն ադմինիստրատորին։ Նույնը վերաբերում է այն ճանապարհին, որին ոչ մի վերջնակետ չի համապատասխանում․ հաճախորդն այնտեղ ստանում է 403, ոչ թե 404։ Յուրաքանչյուր վերջնակետ իր կանոնը նշում է բացահայտ։ Այս լռելյայն վարքը նախատեսված է սխալի դեպքի համար, ոչ թե որպես աշխատանքի եղանակ, որի վրա կարելի է հույս դնել։
Սխալների բոլոր կոդերը
Յուրաքանչյուր մերժման հետ գալիս է անփոփոխ code՝ ծրագրի համար, և կանչողի լեզվով նախադասություն՝
մարդու համար։ Ամբողջական ցուցակը՝ յուրաքանչյուր կոդի HTTP կարգավիճակով, գտնվում է
API-ի սխալների կոդեր էջում։