Ställer du REST API-slutpunkter korrekt?

Ställer du dina API-slutpunkter rätt? Det händer ofta när vi ställer in slutpunkter för våra API:er att vi stöter på situationer där vi är osäkra på om vi ska skriva i plural eller singular. Ska vi använda understreck eller bindestreck? Hur ska vi nämna ID:n? För ett API som skapar en resurs, ska vi använda /resource/create? Och många fler frågor. Så låt oss dyka djupt in i namnkonventionerna för REST API:er. Här täcker vi:

Slutpunkter
Metoder
Versionering

Slutpunkter

Låt oss börja med att gå igenom några namnkonventioner för REST API:er.

Resurser som substantiv

REST API:er bör göra det möjligt för dig att manipulera en resurs genom att använda en av de huvudsakliga HTTP-metoderna. REST-URI:erna bör inte indikera någon sorts CRUD-operationer. De bör hänvisa till en resurs istället för en åtgärd/verb. Använd helst pluralformer av substantiven endast, om det inte är singletonresurser.

Bra exempel:

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

Dåliga exempel:

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

Hierarki

Hierarkin mellan resurser och samlingar definieras genom användningen av snedstreck.

"Liksom allt inom mjukvaruutvecklings hantverk är namngivning kritisk för framgång"

Bra exempel:

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

Dåligt exempel:

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

Bindestreck

Det är allmänt accepterat att läsa bindestreck ( first-name ) är tydligare och mer användarvänligt än att läsa understreck ( first_name ). Så närhelst en REST API-slutpunkt innehåller flera ord är det alltid bättre att använda bindestreck istället för understreck. Plus, det finns ett perspektiv här från SEO-synpunkt också. Det rekommenderas att använda bindestreck eftersom det hjälper botar att identifiera begreppen i URL:en lättare. Och ett understreck mellan två ord betraktas som helhet som ett ord, medan användningen av bindestreck anses vara två separata ord.

Bra exempel:

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

Dåligt exempel

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

Metoder

Vi vet nu att vi inte ska använd verb i våra REST API-slutpunkter, men det väcker frågan om hur vi ska ange verbet då. För detta har vi HTTP-metoder till vår räddning. HTTP-metoder är de verb som anger vilken typ av operation som API:et kan utföra.

HTTP-metoder:

GET motsvarar läsoperationen för en resurs eller en samling.
POST motsvarar skapandet av en resurs eller en samling.
PUT motsvarar uppdateringen av en resurs eller en samling.
DELETE motsvarar borttagningen av en resurs eller en samling.

Det finns totalt 39 HTTP-metoder men GET, POST, PUT och DELETE är de mest använda och grundläggande metoderna. Vi kommer att täcka alla HTTP-metoder och deras användningsfall i en separat blogg.

Versionering

Det är alltid bättre att versionera dina API:er. Samma URL:er kan förbrukas utan att behöva göra några större ändringar i REST API-slutpunkterna. API-slutpunkter bör aldrig invalideras då detta kan få oförutsedda konsekvenser för de program som använder dem.

Exempel:

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

Viktiga punkter

Använd substantiv för att representera resurser.
Undvik att använda verb i REST API-slutpunkterna.
Använd inte understreck (`_`) i en slutpunkt. Använd istället bindestreck (`-`).
Använd frågor för att filtrera, sortera eller begränsa en API-samling.
Lägg aldrig till filtillägg till URL:erna. Om du vill ange innehållstypen, använd istället huvudet `Content-Type`.
Föredra alltid att använda små bokstäver i REST API-slutpunkterna.
Lägg inte till avslutande snedstreck (`/`) i REST API-slutpunkterna. De lägger till inget semantiskt värde och kan vara förvirrande.
Välj enkla namn. Om det görs rätt blir API-slutpunkterna mycket lätta för vilken utvecklare som helst att komma ihåg eller gissa.