Kaip rašyti SaaS API dokumentaciją, kurią kūrėjai iš tikrųjų naudoja

Santrauka

Prasta API dokumentacija yra tylus SaaS augimo žudikas. Kūrėjai atsisako integracijų, pagalbos komandos skęsta klausimuose, o produkto pritaikymas stringa. Šiame straipsnyje pateikiamas patikrintas 5 žingsnių rėmas, kaip rašyti API dokumentaciją, kurią kūrėjai mėgsta ir naudoja. Sužinosite, kaip pradėti nuo greito pradžio vadovo, pateikti nuoseklius pavyzdžius visiems galiniams taškams, išsamiai dokumentuoti klaidų valdymą, išlaikyti versijų valdymą su aiškiais pakeitimų žurnalais ir pridėti interaktyvias konsoles. Realūs pavyzdžiai iš Stripe, Twilio ir GitHub parodo, kas veikia. Pabaigoje turėsite šabloną, kaip savo dokumentaciją paversti iš paskutinės minties į konkurencinį pranašumą, kuris skatina konversijas ir mažina klientų praradimą.

Įvadas

Kiekvienas SaaS įkūrėjas žino šį skausmą: sukūrėte galingą API, bet kūrėjai sunkiai ją integruoja. Pagalbos bilietai kaupiasi, įvedimas užtrunka savaites, o potencialūs klientai renkasi konkurentus su aiškesne dokumentacija. Problema ne jūsų produktas – tai jūsų dokumentacija. Remiantis Stoplight tyrimu, 60% kūrėjų teigia, kad prasta dokumentacija yra pagrindinė priežastis, kodėl jie atsisako API. Šis vadovas tai išsprendžia. Išeisite su konkrečiu 5 žingsnių rėmu, kurį naudoja geriausios SaaS įmonės, kad dokumentaciją paverstų augimo varikliu.

Kodėl puiki API dokumentacija yra svarbi

Jūsų API dokumentacija dažnai yra pirmas tikras kūrėjo sąveika su jūsų produktu. Ji formuoja jų požiūrį į jūsų inžinerijos kultūrą, patikimumą ir naudojimo paprastumą. Puiki dokumentacija sumažina pagalbos apimtį, įgalindama savitarnos paslaugas, pagreitina klientų integracijos laiką ir netgi padidina konversijų rodiklius. Iš tiesų, jūsų API dokumentacija gali būti tokia pat svarbi kaip jūsų kainodaros puslapis kūrėjams orientuotiems produktams. Kai kūrėjas per kelias minutes sukuria veikiančią integraciją, jie tampa jūsų vidiniu šalininku.

1 žingsnis: Pradėkite nuo greito pradžio vadovo

Kūrėjai nenori skaityti romano prieš atlikdami pirmąjį API iškvietimą. Pateikite greito pradžio vadovą, kuris juos nuves nuo nulio iki veikiančio užklausos per mažiau nei 5 minutes. Įtraukite:

• Autentifikacijos nustatymą (pvz., API rakto generavimas)
• Paprastą GET arba POST užklausą naudojant cURL arba jūsų pageidaujamą klientą
• Sėkmingo atsakymo pavyzdį
• Dažnas klaidas (pvz., neteisingos antraštės)

Pavyzdys iš Stripe: Jų greito pradžio vadovas pateikia kopijuojamą cURL komandą, kuri nuskaito kreditinę kortelę. Jokio plepalo. Jei tik pradedate, modeliuokite savąją pagal šį.

2 žingsnis: Pateikite nuoseklius, kalbai būdingus pavyzdžius

Vienas didžiausių nusivylimų API dokumentacijoje yra rasti pavyzdžius jūsų kalba. Apimkite bent 5 populiariausias: cURL, Python, JavaScript, Ruby ir PHP. Išlaikykite identišką struktūrą visose kalbose, kad kūrėjai galėtų protiškai atpažinti šablonus. Kiekvienam galiniam taškui parodykite:

• Užklausos parametrus (privalomi vs neprivalomi)
• Užklausos turinio schemą (JSON)
• Užklausos pavyzdį kiekviena kalba
• Atsakymo pavyzdį su paaiškintais laukais

Išlyga: Nekopijuokite variantų. Naudokite automatinio generavimo įrankius, tokius kaip Postman ar Redoc, kad užtikrintumėte nuoseklumą. Nenuoseklūs pavyzdžiai klaidina ir mažina pasitikėjimą.

3 žingsnis: Išsamiai dokumentuokite klaidas ir kraštinius atvejus

Klaidų valdymas yra vieta, kur dauguma dokumentacijų stringa. Kūrėjai turi žinoti, kas gali suklysti ir kaip tai tvarkyti. Kiekvienam galiniam taškui dokumentuokite:

• Visus galimus HTTP būsenos kodus (200, 400, 401, 404, 429, 500)
• Klaidos atsakymo turinio formatą (pvz., {\"error\": {\"code\": \"invalid_param\", \"message\": \"...\"}})
• Dažnus klaidų scenarijus ir kaip juos išspręsti
• Spartos ribojimo politiką ir pakartotinio bandymo strategijas

Pavyzdys iš Twilio: Jų klaidų dokumentacija išvardija kiekvieną klaidos kodą su žmogui suprantamu pranešimu, priežastimi ir sprendimu. Tai drastiškai sumažina pagalbos bilietus.

4 žingsnis: Išlaikykite versijų valdymą ir aiškų pakeitimų žurnalą

API keičiasi. Be versijų valdymo jūs sugadinate integracijas ir prarandate pasitikėjimą. Naudokite URI versijų valdymą (pvz., /v1/, /v2/) ir aiškiai pažymėkite nebenaudojamus galinius taškus. Be to, tvarkykite pakeitimų žurnalą, kuris:

• Grupuoja pakeitimus pagal versiją
• Pabrėžia esminius pakeitimus paryškinimu arba įspėjimo piktograma
• Pateikia migracijos vadovus svarbioms versijoms
• Nurodo kiekvieno leidimo datą

Pavyzdys iš GitHub: Jų API pakeitimų žurnalas yra aiškumo pavyzdys, su santraukomis ir nuorodomis į išsamius įrašus. Kūrėjai prenumeruoja jį per RSS arba el. paštą.

Išlyga: Niekada nepašalinkite galinio taško be įspėjimo apie nebenaudojimą. Laikykitės nebenaudojimo politikos (pvz., 3 mėnesių įspėjimas). Komunikuokite per el. paštą, tinklaraštį ir dokumentacijos pranešimus.

5 žingsnis: Pridėkite interaktyvias konsoles ir SDK

Leiskite kūrėjams išbandyti iškvietimus tiesiai iš jūsų dokumentacijos. Įrankiai, tokie kaip Swagger UI arba Postman įterptinis vykdiklis, leidžia jiems autentifikuotis, koreguoti parametrus ir matyti tiesioginius atsakymus. Tai sumažina trintį pereinant tarp dokumentacijos ir terminalo. Be to, pateikite oficialius SDK populiarioms kalboms. SDK apgaubia jūsų API vietiniais metodais, taupydami laiką ir mažindami klaidas.

Pavyzdys iš Stripe: Jų API nuorodoje yra mygtukas „Live Demo“, kuris vykdo tikrą užklausą su vartotojo API raktu. Tai aukso standartas.

Viską Sujungiant: Dokumentacijos Šablonas

Kad padėtume jums pradėti, čia yra pagrindinė jūsų dokumentacijos struktūra:

1. Apžvalga – Ką daro API, bazinis URL, autentifikacija
2. Greitas pradžio vadovas – 5 minučių pamoka su kopijuojamu kodu
3. Vadovai – Koncepcijos (puslapiavimas, webhook'ai ir kt.)
4. API Nuoroda – Galiniai taškai sugrupuoti pagal išteklius, kiekvienas su:
   • Aprašymu
   • HTTP metodu ir keliu
   • Parametrais (lentelė su pavadinimu, tipu, privalomumu, aprašymu)
   • Užklausos pavyzdžiu (keliomis kalbomis)
   • Atsakymo pavyzdžiu (su komentarais)
5. Klaidos – Išsamus klaidų kodų ir sprendimų sąrašas
6. Pakeitimų žurnalas – Versijų istorija ir migracijos vadovai
7. Pagalba – Kaip gauti pagalbą (forumas, el. paštas, Slack)

Išvada

Puiki API dokumentacija nėra prabanga; tai būtinybė bet kuriam SaaS, kuris nori, kad kūrėjai priimtų ir reklamuotų jo produktą. Laikydamiesi šių 5 žingsnių – greito pradžio vadovo, nuoseklių pavyzdžių, klaidų dokumentacijos, versijų valdymo ir interaktyvumo – galite savo dokumentaciją iš pagalbos atsakomybės paversti konkurenciniu pranašumu. Pradėkite nuo vienos dalies, tobulinkite remdamiesi vartotojų atsiliepimais ir žiūrėkite į savo dokumentaciją taip pat rimtai kaip į produkto kodą. Jūsų kūrėjai padėkos, o pagalbos komanda turės mažiau bilietų, į kuriuos reikia atsakyti.