Stel je REST API-eindpunten correct in?

Stelt u REST API-eindpunten correct in?

Stelt u uw API-eindpunten correct in? Het gebeurt vaak dat we bij het instellen van eindpunten voor onze API's in situaties terechtkomen waarin we niet zeker weten of we in meervoudsvorm of enkelvoudsvorm moeten schrijven. Moeten we underscores of streepjes gebruiken? Hoe vermelden we ID's? Voor een API die een resource aanmaakt, moeten we /resource/create gebruiken? En nog veel meer. Laten we dus diep ingaan op de naamgeving voor REST API's. Hier behandelen we:

• Eindpunten
• Methoden
• Versiebeheer

Eindpunten

Laten we beginnen met enkele naamgevingsconventies voor REST API's.

Resources als zelfstandige naamwoorden

REST API's moeten u in staat stellen een resource te manipuleren met behulp van een van de hoofdmethoden van HTTP. De REST URI's mogen geen CRUD-bewerkingen aangeven. Ze moeten verwijzen naar een resource in plaats van naar een actie/werkwoord. Gebruik waar mogelijk alleen meervoudsvormen van zelfstandige naamwoorden, tenzij het singleton-resources zijn.

Goede voorbeelden:

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

Slechte voorbeelden:

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

Hiërarchie

De hiërarchie tussen resources en collecties wordt bepaald door het gebruik van slashes.

"Net als alles in het ambacht van softwareontwikkeling is naamgeving van cruciaal belang voor succes"

Goed voorbeeld:

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

Slecht voorbeeld:

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

Streepjes

Het is algemeen aanvaard dat streepjes lezen ( first-name ) duidelijker en gebruiksvriendelijker is dan underscores lezen ( first_name ). Dus, wanneer een REST API-eindpunt uit meerdere woorden bestaat, is het altijd beter om streepjes te gebruiken in plaats van underscores. Bovendien is er hier ook een SEO-perspectief. Het wordt aanbevolen om streepjes te gebruiken, omdat dit bots helpt de concepten in de URL gemakkelijker te identificeren. Een underscore tussen twee woorden wordt als geheel beschouwd als één woord, terwijl het gebruik van streepjes als twee afzonderlijke woorden wordt beschouwd.

Goed voorbeeld:

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

Slecht voorbeeld

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

Methoden

We weten nu dat we geen werkwoorden in onze REST API-eindpunten moeten gebruiken, maar dat roept de vraag op hoe we het werkwoord dan moeten specificeren. Daarvoor hebben we HTTP-methoden. HTTP-methoden zijn de werkwoorden die aangeven wat voor soort bewerking de API mogelijk uitvoert.

HTTP-methoden:

• GET komt overeen met de bewerking "Lezen" van een resource of een collectie.
• POST komt overeen met de bewerking "Aanmaken" van een resource of een collectie.
• PUT komt overeen met de bewerking "Bijwerken" van een resource of een collectie.
• DELETE komt overeen met de bewerking "Verwijderen" van een resource of een collectie.

Er zijn in totaal 39 HTTP-methoden, maar GET, POST, PUT en DELETE zijn de meest gebruikte en basismethoden. We zullen alle HTTP-methoden en hun gebruiksscenario's in een apart blog behandelen.

Versiebeheer

Het is altijd beter om uw API's van een versie te voorzien. Dezelfde URL's kunnen worden gebruikt zonder dat er grote wijzigingen in de REST API-eindpunten hoeven te worden aangebracht. API-eindpunten mogen nooit ongeldig worden gemaakt, omdat dit onvoorziene gevolgen kan hebben voor de toepassingen die ze gebruiken.

Voorbeelden:

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

Belangrijke punten

• Gebruik zelfstandige naamwoorden om resources weer te geven.
• Vermijd het gebruik van werkwoorden in de REST API-eindpunten.
• Gebruik geen underscores (`_`) in een eindpunt. Gebruik in plaats daarvan streepjes (`-`).
• Gebruik query's om een API-collectie te filteren, sorteren of beperken.
• Voeg nooit bestandsextensies toe aan de URL's. Als u het type inhoud wilt specificeren, gebruik dan de `Content-Type`-header.
• Gebruik altijd kleine letters in de REST API-eindpunten.
• Plaats geen afsluitende slashes (`/`) in de REST API-eindpunten. Ze voegen geen semantische waarde toe en kunnen verwarrend zijn.
• Kies eenvoudige namen. Indien correct gedaan, worden API-eindpunten zeer gemakkelijk voor elke ontwikkelaar om te onthouden of in te schatten.