Kazalo:
- Naredi svojo domačo nalogo
- Bodite dosledni
- Uporabite OAuth
- Začnite zgodaj
- Napišite dobro dokumentacijo
- Razvoj API-ja: Naj bo preprosto
To je narava razvoja programske opreme. Razvijalci ustvarjajo programsko opremo v mislih končnega uporabnika. Zdi se precej preprosto, včasih pa so ti uporabniki tudi sodelavci. Ne potrebujejo razčlenjenih stvari zanje. Ne potrebujejo niti preprostosti. Vse, kar želijo, je dostop - način za integracijo programske opreme s svojo. Tukaj prihaja API (vmesnik za programiranje aplikacij). Upam, da bom izpostavil pet korakov, ki jih lahko naredite za ustvarjanje uspešnega API-ja.
Naredi svojo domačo nalogo
Ko gre za razvoj programske opreme, nihče od nas ne želi na novo izumiti kolesa. V tem trenutku imajo skoraj vsa velika spletna podjetja API-je za svoje programske izdelke. Preučite te API-je in poskusite izbrati različne oblikovne odločitve, ki so nastale pri njihovem ustvarjanju.
Tam je veliko različnih tehnologij, vendar bo večina API-jev, ki jih boste videli, uporabljala bodisi vmesnik RESTful bodisi SOAP. Če ste na ograji glede vmesnika API, ki ga boste uporabili, bi predlagal, da se s protokolom HTTP poslužite RESTful pristopa. Enostavnejši je od SOAP-a, trenutno je bolj priljubljen in lažje boste začeti z uporabo spletnega programskega izdelka.
Bodite dosledni
Ena od stvari, ki jo razvijalci najbolj cenijo, je doslednost. To med drugim vključuje naslovljivost, vhodne argumente, izhodne formate in ravnanje z napakami.
Pri uporabi pristopa RESTful obstaja veliko različnih shem poimenovanja URI. Vsak ima svoje podpornike, zato le izberite enega in se ga držite. Enako velja za vhodno in izhodno strukturo. Večina API-jev podpira XML in JSON kot vhodne in izhodne formate. Predlagam, da podprete oboje, vendar izberete privzeto obliko.
Za vnos je treba vaše vhodne zahteve dosledno poimenovati in bi morale biti smiselne v okviru klica API, ki ga opravljate. Za izhod preverite, ali uporabljate skupne postavitve podatkovne strukture. Če izhod enega klica API ovijete v
Običajna praksa je, da se v izhodne podatke, ki jih pošljete stranki, vključi nekakšna zastava stanja. Pri uporabi pristopa API RESTful je to treba storiti z uporabo kod HTTP statusa. Na primer, če ste pravkar obdelali zahtevo PUT na obstoječem podatkovnem objektu, se koda stanja HTTP, ki jo vključite v svoj odgovor, razlikuje glede na izid zahteve.
Namesto poljubne zastavice, ki označuje status klica, lahko za označitev, da je bila zahteva uspešna, uporabite standardno kodo statusa "200 OK", oznako stanja "400 slabe zahteve" pa lahko označite, da je bila zahteva nepravilno oblikovan. Obstaja kar nekaj kode stanja HTTP, ki se lahko uporabljajo v različnih situacijah.
Uporabite OAuth
Večina programskih izdelkov bo za dostop do zaščitenih virov za tega uporabnika vključevala neke vrste overjanje uporabnika. Kar zadeva API-je, je naročilo zbiranje uporabniških poverilnic za pošiljanje na vaš strežnik slaba praksa. Tukaj pride OAuth.
OAuth ponuja številne prednosti glede pristnosti uporabniškega imena / gesla tretjih oseb. Predvsem pa stranka nikoli nima dostopa do uporabniških poverilnic. Ko se uporabnik preusmeri na vaš strežnik, ko se prijavi. Potem ko se uporabnik prijavi na vaše spletno mesto, se preusmeri nazaj na odjemalca, kjer bo odjemalec dobil žeton dostopa, ki ga bo uporabil v prihodnjih zahtevah do zaščitenih virov.
Druga pomembna prednost uporabe OAuth je zmožnost uporabnika kadar koli preklicati dostop do stranke. Če se uporabnik odloči, da zaradi kakršnega koli razloga ne želi več, da bi stranka v njihovem imenu lahko dostopala do zaščitenih virov, se preprosto odpravi na vmesnik, ki ste ga ustvarili, in prekliče dostop stranke.
Začnite zgodaj
Ena od najpomembnejših stvari, ki jo lahko naredite za uspeh API-ja, je, da začnete zgodaj. Ko napišete to funkcijo, da ustvarite nekaj vnosa v svojo bazo podatkov, pojdite naprej in si vzemite dodaten čas ter napišite vmesnik API zanjo.Napišite dobro dokumentacijo
Nič ne ubije API-ja hitreje kot ne imeti dobre dokumentacije. Medtem ko nekateri razvijalci lahko sprejmejo slabo dokumentiran API in ugotovijo, kako naj deluje, večina tega ne želi.
Vsak klic API-ja morate dokumentirati, če imate na voljo, in razvrstiti klice API-ja po vrsti podatkov, na katere delujejo. Skupaj z dokumentiranjem končnih točk za klice API-ja bi morali sistematično definirati zahtevane in neobvezne vhodne argumente ter izhodne podatkovne strukture. Argumenti vnosa morajo navesti privzeto vrednost, če obstaja, in tudi navesti pričakovano obliko podatkov, kot sta številka ali niz. Nazadnje bi moral vsak klic API imeti seznam pogojev napake in kode stanja.
Če želite zaokrožiti svojo dokumentacijo, ne pozabite vključiti enega ali dva primera za skupne vhodne in izhodne scenarije za vsak klic API.
Razvoj API-ja: Naj bo preprosto
Čeprav se morda zdi, da je razvoj API-ja zapleteno prizadevanje, ideja o API-ju sama po sebi ni nov koncept in obstaja velika količina razpoložljive dokumentacije o vsaki temi, ki smo se je dotaknili tukaj. Bodite prepričani, da uporabite dobre prakse, kjer jih lahko najdete, in zagotovite dosleden, dobro dokumentiran vmesnik.
