Turinys:
- Daryk savo namų darbus
- Būkite nuoseklūs
- Naudokite „OAuth“
- Pradėkite anksti
- Parašykite gerą dokumentaciją
- API kūrimas: laikykitės paprasto
Tai yra programinės įrangos kūrimo pobūdis. Kūrėjai kuria programinę įrangą galvodami apie galutinį vartotoją. Atrodo gana paprasta, tačiau kartais tie vartotojai yra ir kolegos kūrėjai. Jiems nereikia suskirstytų daiktų. Jiems nereikia net paprastumo. Jie nori tik prieigos - būdas integruoti savo programinę įrangą su savo. Čia įsijungia API (programų programavimo sąsaja). Tikiuosi pabrėžti penkis veiksmus, kuriuos galite atlikti, norėdami sukurti sėkmingą API.
Daryk savo namų darbus
Kalbant apie programinės įrangos kūrimą, nė vienas iš mūsų nenori išradinėti rato. Šiuo metu beveik visos didelės žiniatinklio bendrovės turi savo programinės įrangos produktų API. Studijuokite šias API ir pabandykite pasirinkti įvairius sprendimus, susijusius su jų kūrimu.
Yra daugybė skirtingų technologijų, tačiau dauguma API, kurias pamatysite, bus naudojamos RESTful sąsaja arba SOAP. Jei esate ant tvoros, kuria API sąsaja naudositės, aš siūlyčiau naudoti RESTful metodą, naudojant HTTP protokolą. Tai paprastesnis nei SOAP, šiuo metu jis yra populiaresnis, o pradėti naudoti bus lengviau, kai naudosite internetinį programinės įrangos produktą.
Būkite nuoseklūs
Vienas iš dalykų, kurį kūrėjai labiausiai vertina, yra nuoseklumas. Tai, be kita ko, apima adresuojamumą, įvesties argumentus, išvesties formatus ir klaidų tvarkymą.
Kai naudojamas RESTful metodas, yra daugybė skirtingų URI įvardijimo schemų. Kiekvienas iš jų turi savo šalininkus, todėl tiesiog pasirinkite vieną ir laikykitės jo. Tas pats pasakytina apie įvesties ir išvesties struktūrą. Daugelis API palaiko XML ir JSON kaip įvesties ir išvesties formatus. Siūlyčiau palaikyti abu, tačiau pasirinkti numatytąjį formatą.
Norėdami įvesti duomenis, jūsų įvesties reikalavimai turėtų būti nurodomi nuosekliai ir turėtų būti prasmingi atsižvelgiant į jūsų API skambutį. Norėdami gauti išvestį, įsitikinkite, kad naudojate įprastus duomenų struktūros išdėstymus. Jei įvyniojate vieno API skambučio išvestį
Įprasta, kad į išvestinius duomenis, kuriuos siunčiate atgal klientui, reikia įtraukti tam tikros būklės vėliavą. Naudojant RESTful API metodą, tai turėtų būti daroma naudojant HTTP būsenos kodus. Pavyzdžiui, jei ką tik apdorojote PUT užklausą dėl esamo duomenų objekto, HTTP būsenos kodas, kurį įtraukėte į savo atsakymą, skirsis priklausomai nuo užklausos rezultato.
Vietoj savavališkos vėliavos, nurodančios skambučio būseną, gali būti naudojamas standartinis „200 gerai“ būsenos kodas, kuris reiškia, kad užklausa buvo sėkminga, o būsenos kodas „400 blogo prašymo“ gali būti naudojamas norint nurodyti, kad užklausa buvo atlikta. netinkamai suformuotas. Yra gana daug HTTP būsenos kodų, kuriuos galima naudoti įvairiose situacijose.
Naudokite „OAuth“
Daugeliui programinės įrangos produktų bus reikalingas tam tikras vartotojo autentifikavimas, kad būtų galima pasiekti to vartotojo apsaugotus išteklius. Kalbant apie API, kliento reikalavimas surinkti vartotojo kredencialus, kuriuos reikia nusiųsti į jūsų serverį, yra bloga praktika. Čia ateina „OAuth“.
„OAuth“ teikia daug pranašumų, palyginti su trečiųjų šalių vartotojo vardo / slaptažodžio autentifikavimu. Visų pirma, klientas niekada neturi prieigos prie vartotojo kredencialų. Prisijungęs vartotojas nukreipiamas į jūsų serverį. Kai vartotojas prisijungia prie jūsų svetainės, jis yra nukreipiamas atgal į klientą, kur klientas gaus prieigos raktą, kurį galės naudoti būsimose saugomų išteklių užklausose.
Kitas svarbus „OAuth“ naudojimo pranašumas yra vartotojo galimybė bet kada atšaukti kliento prieigą. Jei vartotojas nusprendžia, kad dėl kokių nors priežasčių jie nebenori, kad klientas galėtų jo vardu pasiekti apsaugotus išteklius, jis paprasčiausiai eina į jūsų sukurtą sąsają ir atšaukia kliento prieigą.
Pradėkite anksti
Vienas iš svarbiausių dalykų, kuriuos galite padaryti, kad jūsų API būtų sėkminga, yra pradėti naudoti anksti. Rašydami šią funkciją norėdami sukurti kokį nors įrašą savo duomenų bazėje, eikite į priekį ir skirkite papildomo laiko bei parašykite jai API sąsają.Parašykite gerą dokumentaciją
Niekas neužmuša API greičiau, nei neturint geros dokumentacijos. Nors kai kurie kūrėjai gali naudoti blogai dokumentuotą API ir išsiaiškinti, kaip ji turėtų veikti, dauguma to nenorės.
Turėtumėte dokumentuoti kiekvieną turimą API skambutį ir suskirstyti savo API skambučius į kategorijas, pagal kurią jie veikia. Kartu su pačių API kvietimų baigčių dokumentavimu, turėtumėte sistemingai apibrėžti reikiamus ir pasirenkamus įvesties argumentus, taip pat išvesties duomenų struktūras. Įvestų argumentų sąraše turėtų būti numatytoji reikšmė, jei tokia yra, ir nurodomas numatomas duomenų formatas, pavyzdžiui, skaičius ar eilutė. Galiausiai kiekvienas API skambutis turėtų turėti klaidų sąlygų ir būsenos kodų sąrašą.
Norėdami suapvalinti savo dokumentus, būtinai įtraukite vieną ar du kiekvieno API skambučio įvesties ir išvesties scenarijų pavyzdžius.
API kūrimas: laikykitės paprasto
Nors gali atrodyti, kad API sukūrimas yra sudėtingas siekis, pati API idėja nėra nauja koncepcija ir kiekvienoje čia aptartoje temoje yra daug dokumentų. Tiesiog būtinai naudokitės gerąja patirtimi ten, kur jas galite rasti, ir pateikite nuoseklią, gerai dokumentuotą sąsają.
