Asetatko REST API -päätepisteitä oikein?

Asetatko API-päätepisteitäsi oikein? Usein silloin, kun asetamme päätepisteitä API:llemme, törmäämme tilanteisiin, joissa emme ole varmoja, kirjoitetaanko monikko vai yksikkö. Pitäisikö käyttää alaviivoja vai väliviivoja? Kuinka mainita tunnisteita? API:lle, joka luo resurssin, pitäisikö käyttää /resource/create? Ja paljon muuta. Joten sukelltetaan syvemmälle REST API:jen nimeämiskäytäntöihin. Tässä käsittelemme:

Päätepisteet
Metodit
Versiointi

Päätepisteet

Aloitamme käymällä läpi joitakin REST API:n nimeämiskäytäntöjä.

Resurssit substantiiveina

REST API:iden tulee sallia resurssin käsittely käyttämällä yhtä pääasialaisista HTTP-metodeista. REST URI:iden ei tulisi ilmaista minkäänlaisia CRUD-operaatioita. Niiden tulisi viitata resurssiin sen sijaan, että ne viittaisivat toimintoon/verbiin. Kun mahdollista, käytä vain substantiivien monikkoa, ellei ne ole singleton-resursseja.

Hyviä esimerkkejä:

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

Huonoja esimerkkejä:

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

Hierarkia

Resurssien ja kokoelmien välinen hierarkia määritetään kauttaviivoja käyttämällä.

"Kuten kaikessa ohjelmistokehityksen taidossa, nimeäminen on kriittinen menestyksen kannalta"

Hyvä esimerkki:

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

Huono esimerkki:

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

Väliviivat

On laajalti hyväksyttyä, että väliviivoja ( first-name ) lukeminen on selkeämpää ja käyttäjäystävällistä kuin alaviivoja ( first_name ) lukeminen. Joten aina kun REST API -päätepisteen nimi sisältää useita sanoja, on parempi käyttää väliviivoja alaviivoja vastaavasti. Lisäksi on näkökulma SEO:n näkökulmasta. On suositeltavaa käyttää väliviivoja, koska se auttaa botteja tunnistamaan URL:n käsitteet helpommin. Ja alaviiva kahden sanan välissä katsotaan kokonaisuutena yhdeksi sanaksi, kun taas väliviivoja käyttäminen katsotaan kahdeksi erilliseksi sanaksi.

Hyvä esimerkki:

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

Huono esimerkki

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

Metodit

Tiedämme nyt, että REST API -päätepisteissä ei tulisi käyttää verbejä, mutta se herättää kysymyksen siitä, kuinka verbi määritetään. Tähän apuun tulevat HTTP-metodit. HTTP-metodit ovat verbit, jotka ilmaisevat, minkä tyyppisen operaation API saattaa suorittaa.

HTTP-metodit:

GET vastaa resurssin tai kokoelman "Lukemisen" operaatiota.
POST vastaa resurssin tai kokoelman "Luomisen" operaatiota.
PUT vastaa resurssin tai kokoelman "Päivittämisen" operaatiota.
DELETE vastaa resurssin tai kokoelman "POISTAMISEN" operaatiota.

HTTP-metodeja on yhteensä 39, mutta GET, POST, PUT ja DELETE ovat yleisimmin käytetyt ja perusmetodit. Käsittelemme kaikki HTTP-metodit ja niiden käyttökohteet erillisessä blogissa.

Versiointi

On aina parempi versioda API:si. Samoja URL:eja voidaan käyttää ilman, että REST API -päätepisteissä tarvitsee tehdä suuria muutoksia. API-päätepisteitä ei tulisi koskaan mitätöidä, koska tämä saattaa aiheuttaa odottamattomia seurauksia niitä käyttäville sovelluksille.

Esimerkkejä:

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

Tärkeimmät kohdat

Käytä substantiivia resurssien edustamiseen.
Vältä verbien käyttöä REST API -päätepisteissä.
Älä käytä alaviivoja (`_`) päätepistessä. Käytä sen sijaan väliviivoja (`-`).
Käytä kyselyitä API-kokoelman suodattamiseen, lajitteluun tai rajoittamiseen.
Älä koskaan lisää tiedostojen tunnisteita URL:iin. Jos haluat määrittää sisällön tyypin, käytä `Content-Type` -otsikkoa.
Käytä aina pieniä kirjaimia REST API -päätepisteissä.
Älä laita perässä olevia kauttaviivoja (`/`) Rest API:n päätepisteisiin. Ne eivät lisää semanttista arvoa ja voivat olla hämmentäviä.
Valitse yksinkertaisia nimiä. Jos se tehdään oikein, API-päätepisteet tulevat erittäin helpoiksi millä tahansa kehittäjällä muistaa tai arvata.