Ես կգրեմ հստակ API փաստաթղթեր, որոնց ձեր ծրագրավորողները կարող են հետևել առաջին իսկ օրվանից

Ինչու են API փաստաթղթերի մեծ մասը ձախողվում

Նրանք նկարագրում են վերջնակետերը և բաց են թողնում այն մասերը, որոնք իրականում կանգնեցնում են մարդկանց՝ ինչպես նույնականացնել, ինչպիսին է իրատեսական հարցումը, ինչ է նշանակում սխալը և ինչ անել դրա հետ։ Այնուհետև ընթերցողը բացում է աջակցության տոմս, որը փաստաթղթավորման գինն է, որը գոյություն ունի հեռացնելու համար։

Ինչպես եմ ես գրում այն

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

Ինչ է պարունակում փաստաթղթերը

• Նույնականացում. թոքեն ստանալը, այն թարմացնելը և ինչ է տեղի ունենում, երբ այն ժամկետանց է լինում նիստի ընթացքում։
• Յուրաքանչյուր վերջնակետ պարամետրերով, ամբողջական օրինակ հարցումով և իրական պատասխանի ձևով։
• Սխալների հղում, որը յուրաքանչյուր սխալի կոդը քարտեզագրում է պատճառի և ուղղման հետ, այլ ոչ թե պարզապես կրկնում է հաղորդագրությունը։
• Սկսելու ուղի, որը նոր ծրագրավորողին զրոյից հասցնում է հաջող զանգի տասը րոպեից պակաս ժամանակում։
• Սահմանափակումներ, էջադրում, վեբհուքեր և իդեմպոտենտություն՝ բացատրված այնտեղ, որտեղ դրանք իրականում կիրառվում են։

Ձևաչափ

Markdown ձեր պահոցում, կառուցվածքային OpenAPI-ի կամ փաստաթղթերի կայքի համար՝ որն էլ որ իրականում կպահպանեք։ Կոդի նմուշներ այն լեզուներով, որոնց մասին հարցնում են ձեր օգտատերերը, հաստատված դրանք գործարկելով։ Postman կամ նմանատիպ հավաքածու ներառված է, եթե ցանկանում եք։

Ինչն է ինձ անհրաժեշտ

Պահոցի մուտք կամ OpenAPI ֆայլը, մեկ աշխատող հավատարմագիր թեստային միջավայրի համար և ցանկացած հարց, որոնց ձեր աջակցության թիմը հոգնել է պատասխանելուց։ Այդ հարցերը ուրվագիծն են։

Ներառված չէ

Մարքեթինգային տեքստ։ Սա փաստաթղթավորում է, թե ինչ է անում ծրագրակազմը, հստակորեն. վայրէջքի էջը այլ արհեստ է։

Շրջադարձ և հաղորդակցություն

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