RESTful API dizajn - Vodič kroz korak

(Donekle) definitivni vodič za izgradnju boljih API-ja

Fotografiju Marius Masalar na Unsplash

Kao programeri softvera, većina nas koristi ili gradi REST API-jeve u svakodnevnom životu. API-ji su zadana sredstva komunikacije između sustava. Amazon je najbolji primjer kako se API-ji mogu učinkovito koristiti za komunikaciju.

U ovom ću članku govoriti o tome kako bolje dizajnirati svoje RESTful API-je kako bi se izbjegle uobičajene pogreške.

Mandat Jeffa Bezosa (ključ uspjeha)

Neki od vas možda su već znali za mandat Jeffa Bezosa programerima u Amazonu. Ako nikada niste dobili priliku čuti za to, srž je toga u nastavku.

  1. Svi će timovi od danas izložiti svoje podatke i funkcionalnost putem sučelja usluge.
  2. Timovi moraju međusobno komunicirati putem ovih sučelja.
  3. Neće biti dozvoljen drugi oblik međuprocesne komunikacije - nema izravnog povezivanja, izravnog čitanja spremišta podataka drugog tima, nema zajedničke memorije, nema stražnjih vrata. Dopuštena je jedino komunikacija putem poziva putem sučelja putem mreže.
  4. Nije važno koju tehnologiju koriste. HTTP, Corba, Pubsub, prilagođeni protokoli - nije važno. Bezosa to ne zanima.
  5. Sva servisna sučelja, bez iznimke, moraju biti dizajnirana od početka do kraja kako bi bila eksternalizirana. Odnosno, tim mora planirati i dizajnirati kako bi mogao izložiti sučelje programerima u vanjskom svijetu. Nema izuzetaka.
  6. Svi koji to ne učine, bit će otpušten.

Na kraju se to pokazalo ključnim za uspjeh Amazona. Amazon bi mogao izgraditi skalabilne sustave, a kasnije bi ih mogao ponuditi i kao usluge poput Amazon Web Services.

Principi dizajniranja RESTful API-ja

A sada da razumemo principe kojih bismo se trebali pridržavati prilikom dizajniranja RESTful API-ja.

Neka bude jednostavno

Moramo biti sigurni da je osnovni URL API-ja jednostavan. Na primjer, ako želimo dizajnirati API-je za proizvode, ona bi trebala biti dizajnirana kao:

/ proizvodi
/ proizvodi / 12345

Prvi API je nabaviti sve proizvode, a drugi je dobiti određeni proizvod.

Koristite imenice, a ne glagole

Puno programera čini ovu pogrešku. Obično zaboravljaju da kod nas imaju HTTP metode za bolji opis API-ja i završavanje upotrebe glagola u URL-ovima API-ja. Na primjer, API za dobivanje svih proizvoda trebao bi biti:

/ proizvodi

a ne kao što je prikazano u nastavku

/ getAllProducts

Do sada sam vidio neke uobičajene URL obrasce.

Korištenje pravih HTTP metoda

RESTful API-ji imaju različite metode koje ukazuju na vrstu operacije koju ćemo izvoditi s ovim API-jem.

  • GET - Da biste dobili resurs ili kolekciju resursa.
  • POST - da biste stvorili resurs ili kolekciju resursa.
  • PUT / PATCH - Ažuriranje postojećeg resursa ili zbirke resursa.
  • DELETE - Brisanje postojećeg resursa ili zbirke resursa.

Moramo biti sigurni da koristimo ispravnu HTTP metodu za datu operaciju.

Upotrijebite množinu

Ova je tema pomalo diskutabilna. Neki vole zadržati URL resursa s množinskim imenima, dok ga drugi vole zadržati jedinstvenim. Na primjer -

/ proizvodi
/proizvod

Volim to održavati u množini, jer izbjegavam zabune u pitanju govorimo li o dobivanju pojedinačnog resursa ili zbirke. Također se izbjegava dodavanje dodatnih stvari poput dodavanja svih na osnovni URL, npr. / Proizvod / sve

Nekima se ovo možda neće svidjeti, ali moj jedini prijedlog je da to bude ujednačeno u cijelom projektu.

Upotrijebite parametre

Ponekad trebamo imati API koji bi trebao više pričati nego id. Ovdje bismo trebali koristiti parametre upita za dizajn API-ja.

  • / products? name = 'ABC' bi trebao biti preferiran nad / getProductsByName
  • / products? type = 'xyz' treba preferirati nad / getProductsByType

Na taj način možete izbjeći duge URL-ove sa jednostavnošću u dizajnu.

Koristite ispravne HTTP kodove

Imamo dosta HTTP kodova. Većina nas završi samo s dvije - 200 i 500! To sigurno nije dobra praksa. Slijedi nekoliko često korištenih HTTP kodova.

  • 200 OK - Ovo je najčešće korišten HTTP kôd koji pokazuje da je izvedena operacija uspješna.
  • 201 CREATED - Ovo se može upotrijebiti kada koristite metodu POST za stvaranje novog resursa.
  • 202 PRIHVATLJIVO - ovo se može koristiti za potvrdu zahtjeva poslanog poslužitelju.
  • ZAHTJEV ZA 400 BAD - Ovo se može koristiti kada neuspjeh provjere unosa na strani klijenta.
  • 401 UNAUTHORIZED / 403 FORBIDDEN - Ovo se može koristiti ako korisnik ili sustav nisu ovlašteni za određeni zahvat.
  • 404 NOT FOUND - To se može koristiti ako tražite određeni resurs i nije dostupan u sustavu.
  • 500 GREŠKA UNUTARNJI SERVERA - To se nikada ne smije izričito bacati, ali može se dogoditi ako sustav ne uspije.
  • 502 BAD GATEWAY - Ovo se može koristiti ako je poslužitelj primio nevažeći odgovor od uzvodnog poslužitelja.

Verziranje

Verzija API-ja vrlo je važna. Mnoge različite tvrtke koriste verzije na različite načine. Neki koriste verzije kao datume, dok neke koriste verzije kao parametre upita. Obično ga volim držati prefiksirano na resursu. Na primjer:

/ V1 / proizvoda
/ V2 / proizvoda

Također bih htio izbjegavati upotrebu /v1.2/products, jer podrazumijeva da bi se API često mijenjao. Također, točke (.) Možda neće biti lako vidljive u URL-ovima. Dakle, neka bude jednostavno.

Uvijek je dobra praksa zadržati unatrag kompatibilnost tako da ako promijenite API verziju, potrošači dobivaju dovoljno vremena za prelazak na sljedeću verziju.

Upotrijebite stranicu

Korištenje stranice za paginiranje je neophodno kada izlažete API koji može vratiti ogromne podatke, a ako se ne izvrši pravilno uravnoteženje opterećenja, potrošač bi mogao završiti spuštanjem usluge. Moramo uvijek imati na umu da bi API dizajn trebao biti pun dokaz i glup dokaz.

Ovdje se preporučuje uporaba ograničenja i pomaka. Na primjer, / products? Limit = 25 & offset = 50. Također se savjetuje da zadrže zadani limit i zadani offset.

Podržani formati

Važno je i odabrati način reagiranja vašeg API-ja. Većina modernih aplikacija trebala bi vratiti JSON odgovore, osim ako nemate naslijeđenu aplikaciju koja još uvijek mora dobiti XML odgovor.

Koristite ispravne poruke o pogrešci

Uvijek je dobra praksa zadržati skup poruka o pogreškama koje aplikacija šalje i odgovoriti na njih pravilnim id-om. Na primjer, ako koristite API-je za grafikon Facebooka, u slučaju grešaka, vraća poruku poput ove:

{
  "greška": {
    "message": "(# 803) Neki pseudonimi koji ste tražili ne postoje: proizvodi",
    "type": "OAuthException",
    "kôd": 803,
    "fbtrace_id": "FOXX2AhLh80"
  }
}

Vidio sam i nekoliko primjera u kojima ljudi vraćaju URL s porukom o pogrešci, što vam govori više o poruci pogreške i načinu na koji je također moguće obraditi.

Korištenje OpenAPI specifikacija

Kako bi se svi timovi u vašoj tvrtki pridržavali određenih principa, upotreba OpenAPI specifikacija može biti korisna. OpenAPI omogućava vam da prvo dizajnirate svoje API-je i podijelite to s potrošačima na lakši način.

Zaključak

Sasvim je očito da ako želite komunicirati bolje, API su put. Ali ako su osmišljeni loše, tada bi to moglo povećati zbrku. Dakle, uložite sve od sebe u dobro projektiranje, a ostalo je samo implementacija.

Hvala na čitanju

Ako ste naišli na bolje načine dizajniranja API-ja, slobodno ih podijelite u odjeljku s komentarima. Sve povratne informacije su dobrodošle!