5 koraka za stvaranje uspješnog api

To je priroda razvoja softvera. Programeri stvaraju softver s ciljem krajnjeg korisnika. Čini se prilično jednostavno, ali ponekad su ti korisnici i suradnici. Ne trebaju im stvari razbijene. Ne trebaju čak ni jednostavnost. Sve što žele je pristup - način da integriraju svoj softver sa svojim. Ovo je mjesto gdje dolazi API (programsko sučelje za aplikacije). Nadam se da ću istaknuti pet koraka koje možete poduzeti za stvaranje uspješnog API-ja.

Napiši domaću zadaću

Kada je u pitanju razvoj softvera, nitko od nas ne želi izumiti kotač. U ovom trenutku gotovo sve velike web tvrtke imaju API za svoje softverske proizvode. Proučite ove API-je i pokušajte potražiti različite dizajnerske odluke koje su kreirale u njihovom stvaranju.

Postoji mnogo različitih tehnologija vani, ali većina API-ja koje ćete vidjeti upotrebljavat će ili RESTful sučelje ili SOAP. Ako ste na ogradi za API sučelje koje ćete koristiti, predlažem vam da krenete s RESTful pristupom koristeći HTTP protokol. Jednostavniji je od SOAP-a, trenutno je popularniji i bit će lakše započeti s korištenjem web-softverskog proizvoda.

Budite dosljedni

Jedna od stvari koja programeri najviše cijene je dosljednost. To između ostalog uključuje i adresabilnost, argumente unosa, formate izlaza i rukovanje pogreškama.

Kada koristite RESTful pristup, postoji mnogo različitih shema imenovanja URI. Svaka ima svoje pristalice, pa samo odaberite jednog i držite se toga. Isto vrijedi i za strukturu ulaza i izlaza. Većina API-ja podržava XML i JSON kao ulazne i izlazne formate. Preporučio bih podržati i jedno i drugo, ali odabrati zadani format.

Za unos, zahtjevi za unosom trebaju biti dosljedno imenovani i trebali bi imati smisla u kontekstu API poziva koji upućujete. Za izlaz provjerite upotrebljavate li uobičajene rasporede podataka. Ako zaključujete izlaz jednog API poziva u a XML oznaka, razmislite o tome i sa ostalim pozivima.

Uobičajena je praksa da u izlazne podatke koje pošaljete klijentu uključite neku vrstu zastave statusa. Kada koristite RESTful API pristup, to bi trebalo biti učinjeno pomoću HTTP kodova statusa. Na primjer, ako ste upravo obradili PUT zahtjev na postojećem podatkovnom objektu, HTTP statusni kôd koji uključite u svoj odgovor ovisit će ovisno o ishodu zahtjeva.

Umjesto proizvoljne zastave koja označava status poziva, standardni oznaka statusa "200 OK" može se koristiti za označavanje da je zahtjev uspio, dok bi se statusni kôd "400 zahtjeva" mogao upotrijebiti za označavanje da je zahtjev u ispravnom obliku. Postoji nekoliko HTTP kodova statusa koji se mogu koristiti u različitim situacijama.

Koristite OAuth

Većina softverskih proizvoda uključivat će neku vrstu provjere autentičnosti korisnika radi pristupa zaštićenim resursima za tog korisnika. Kad je riječ o API-ima, loša je praksa da klijent prikuplja korisničke vjerodajnice za slanje na vaš poslužitelj. Tu dolazi OAuth.

OAuth pruža brojne prednosti u odnosu na provjeru autentičnosti korisničkog imena / zaporke treće strane. Povrh svega, klijent nikada nema pristup korisničkim vjerodajnicama. Korisnik se preusmjerava na vaš poslužitelj kad se prijavi. Nakon što se korisnik prijavi na vašu web lokaciju, preusmjerava se natrag klijentu gdje će klijent dobiti pristupni token koji će koristiti u budućim zahtjevima zaštićenim resursima.

Druga važna prednost korištenja OAuth-a je korisnikova sposobnost da u bilo kojem trenutku otkaže pristup klijentu. Ako korisnik odluči da, iz bilo kojeg razloga, više ne želi da klijent može pristupiti zaštićenim izvorima u njihovo ime, jednostavno prelazi na sučelje koje ste stvorili i otkazuje klijentov pristup.

Počnite rano

Jedna od najvažnijih stvari koju možete učiniti da vaš API bude uspješan jest pokretanje rano. Kad napišete tu funkciju da napravite neki unos u svojoj bazi podataka, nastavite i iskoristite dodatno vrijeme i za to napišite API sučelje.

Napišite dobru dokumentaciju

Ništa ne ubija API brže od toga što nema dobru dokumentaciju. Iako neki programeri mogu uzeti loše dokumentirani API i shvatiti kako to treba raditi, većina to neće htjeti.

Trebali biste dokumentirati svaki API poziv koji imate na raspolaganju i kategorizirati API pozive prema vrsti podataka na koje djeluju. Uz dokumentiranje krajnjih točaka za same pozive API-ja, trebali biste sustavno definirati potrebne i fakultativne ulazne argumente kao i izlazne strukture podataka. Argumenti unosa trebaju navesti zadanu vrijednost ako ih ima, a također treba navesti očekivani format podataka, kao što su broj ili niz. Napokon, svaki API poziv trebao bi imati popis uvjeta pogreške i kodova statusa.

Da biste zaokružili svoju dokumentaciju, obavezno uključite jedan ili dva primjera za zajedničke ulazne i izlazne scenarije za svaki API poziv.

Razvoj API-ja: Neka bude jednostavno

Iako se može činiti da je razvoj API-ja složen poduhvat, sama ideja API-ja nije novi koncept i postoji velika količina dostupne dokumentacije o svakoj temi koju smo ovdje dotakli. Samo pripazite da koristite dobre prakse gdje ih možete pronaći i da pružite konzistentno i dobro dokumentirano sučelje.