Indstiller du REST API-endpoints korrekt?

Indstiller du dine API-endpoints rigtigt? Det er ofte, når vi indstiller endpoints til vores API'er, at vi støder på situationer, hvor vi ikke er sikre på, om vi skal skrive i flertal eller ental. Skal vi bruge understreg eller bindestreg? Hvordan skal vi angive ID'er? For et API, der opretter en ressource, skal vi bruge /resource/create? Og meget mere. Så lad os dykke ned i navngivningskonventioner for REST API'er. Her dækker vi:

Endpoints
Metoder
Versionering

Endpoints

Lad os starte med at gennemgå nogle REST API-navngivningskonventioner.

Ressourcer som substantiver

REST API'er bør give dig mulighed for at manipulere en ressource ved hjælp af en af de vigtigste HTTP-metoder. REST URI'erne bør ikke angive nogen form for CRUD-operationer. De bør referere til en ressource i stedet for en handling/verb. Når det er muligt, skal du kun bruge flertal af substantiver, medmindre de er singleton-ressourcer.

Gode eksempler:

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

Dårlige eksempler:

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

Hierarki

Hierarkiet mellem ressourcer og samlinger defineres ved brugen af skråstreger.

"Som med alt inden for håndværket softwareudvikling er navngivning kritisk for succes"

Godt eksempel:

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

Dårligt eksempel:

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

Bindestreg

Det er bredt accepteret, at læsning af bindestreg ( first-name ) er klarere og mere brugervenlig end læsning af understreg ( first_name ). Så når en REST API-endpoint indeholder flere ord, er det altid bedre at bruge bindestreg i stedet for understreg. Plus der er en vinkel her fra et SEO-perspektiv også. Det anbefales at bruge bindestreg, da det hjælper bots til at identificere begreberne i URL'en lettere. Og en understreg mellem to ord betragtes som helhed som et ord, hvorimod brugen af bindestreg anses for at være to separate ord.

Godt eksempel:

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

Dårligt eksempel

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

Metoder

Vi ved nu, at vi ikke skal bruge verber i vores REST API-endpoints, men det rejser spørgsmålet om hvordan man angiver verbet. Til dette har vi HTTP-metoder til at redde. HTTP-metoder er verberne, som angiver den slags operation, som API'et kan være ved at udføre.

HTTP-metoder:

GET svarer til "Læs"-operationen af en ressource eller en samling.
POST svarer til "Opret"-operationen af en ressource eller en samling.
PUT svarer til "Opdater"-operationen af en ressource eller en samling.
DELETE svarer til "Slet"-operationen af en ressource eller en samling.

Der er i alt 39 HTTP-metoder, men GET, POST, PUT & DELETE er de mest almindeligt anvendte og grundlæggende metoder. Vi vil dække alle HTTP-metoderne og deres use cases i en separat blog.

Versionering

Det er altid bedre at versionere dine API'er. De samme URL'er kan forbruges uden at skulle foretage større ændringer i REST API-endpoints. API-endpoints bør aldrig ugyldiges, da dette kan få uforudsete konsekvenser for de applikationer, der forbruger dem.

Eksempler:

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

Vigtige punkter

Brug substantiver til at repræsentere ressourcer.
Undgå at bruge verber i REST API-endpoints.
Brug ikke understre (`_`) i et endpoint. Brug i stedet bindestreg (`-`).
Brug forespørgsler til at filtrere, sortere eller begrænse en API-samling.
Tilføj aldrig filtyper til URL'erne. Hvis du vil angive typen af indhold, skal du bruge `Content-Type`-headeren.
Foretrække altid at bruge små bogstaver i REST API-endpoints.
Brug ikke efterfølgende skråstreger (`/`) i REST API-endpoints. De tilføjer ingen semantisk værdi og kan være forvirrende.
Vælg simple navne. Hvis det gøres korrekt, vil API-endpoints blive meget lette for enhver udvikler at huske eller gætte.