Postavljate li REST API krajnje točke ispravno?

Postavljate li REST API krajnje točke ispravno?

Postavljate li svojstvo API krajnje točke ispravno? Često se, pri postavljanju krajnjih točaka naših API-ja, nađemo u situacijama gdje nismo sigurni trebamo li pisati u množini ili jednini. Trebamo li koristiti podcrte ili crtice? Kako spomenuti ID-eve? Za API koji kreira resurs trebamo li koristiti /resource/create? I još mnogo toga. Zato ćemo se detaljno uroniti u konvencije nazivanja REST API-ja. Ovdje ćemo pokrivati:

• Krajnje točke
• Metode
• Verzioniranje

Krajnje točke

Počnimo od nekoliko konvencija nazivanja REST API-ja.

Resursi kao imenice

REST API-ji bi trebali omogućiti manipulaciju resursom koristeći jednu od glavnih HTTP metoda. REST URI-ji ne trebali bi naznačavati bilo koju vrstu CRUD operacija. Trebali bi se odnositi na resurs umjesto na akciju/glagol. Kad god je moguće, koristite samo oblike množine imenica, osim ako nisu singleton resursi.

Dobri primjeri:

• https://api.website.com/v1/store/products
• https://api.website.com/v1/store/customers
• https://api.website.com/v1/store/discounts

Loši primjeri:

• https://api.website.com/v1/store/createproducts
• https://api.website.com/v1/store/updatecustomers
• https://api.website.com/v1/store/getdiscounts

Hijerarhija

Hijerarhija između resursa i zbirki definira se upotrebom kosa crta.

"Kao sa svime u struci razvoja softvera, nazivanje je kritično za uspjeh"

Dobar primjer:

• https://api.website.com/v1/item/store

Loš primjer:

• https://api.website.com/v1/store/items

Crtice

Široko je prihvaćeno da je čitanje crtica ( first-name ) jasnije i korisničnije nego čitanje podcrta ( first_name ). Zato, kad god REST API krajnja točka sadrži više riječi, uvijek je bolje koristiti crtice umjesto podcrta. Osim toga, tu je i SEO perspektiva. Preporuča se korištenje crtica jer pomaže botovima da lakše prepoznaju koncepte u URL-u. Podcrta između dvije riječi smatra se kao cijela riječ, dok se korištenje crtica smatra kao dvije odvojene riječi.

Dobar primjer:

• https://api.website.com/v1/store/inventory-management/active-orders

Loš primjer

• https://api.website.com/v1/store/inventory_management/active_orders

Metode

Sada znamo da ne trebamo koristiti glagole u REST API krajnjim točkama, ali se postavlja pitanje kako tada odrediti glagol. Za to nam na pomoć dolaze HTTP metode. HTTP metode su glagoli koji označavaju vrstu operacije koju API može izvršavati.

HTTP metode:

• GET odgovara operaciji "Čitanja" resursa ili zbirke.
• POST odgovara operaciji "Kreiranja" resursa ili zbirke.
• PUT odgovara operaciji "Ažuriranja" resursa ili zbirke.
• DELETE odgovara operaciji "Brisanja" resursa ili zbirke.

Postoji ukupno 39 HTTP metoda, ali su GET, POST, PUT i DELETE najčešće korištene i osnovne metode. Sve HTTP metode i njihove slučajeve korištenja pokrivat ćemo u zasebnom blogu.

Verzioniranje

Uvijek je bolje verzionirati svoje API-je. Isti URL-ovi mogu se koristiti bez potrebe za većim promjenama u REST API krajnjim točkama. API krajnje točke nikada ne trebaju biti nevaljane jer to može imati neočekivane posljedice za aplikacije koje ih koriste.

Primjeri:

• https://api.website.com/v1/store/items
• https://api.webiste.com/v2/store/employees

Ključne točke

• Koristite imenice za prikaz resursa.
• Izbjegavajte korištenje glagola u REST API krajnjim točkama.
• Ne koristite podcrtavanja (`_`) u krajnjoj točki. Umjesto toga koristite crtice (`-`).
• Koristite upite za filtriranje, sortiranje ili ograničavanje kolekcije API-ja.
• Nikada ne dodavajte proširenja datoteka URL-ovima. Ako želite odrediti tip sadržaja, koristite `Content-Type` zaglavlje.
• Uvijek preferirajte korištenje malih slova u REST API krajnjim točkama.
• Ne stavljajte završne kose crte (`/`) u REST API krajnje točke. Nisu od semantičke vrijednosti i mogu biti zbunjujuće.
• Odaberite jednostavna imena. Ako je ispravno učinjeno, API krajnje točke postaju vrlo lagane za bilo kojeg programera za pamćenje ili pogađanje.