Nastavujete správně REST API Endpoints?

Nastavujete své API endpoints správně? Často se při nastavování endpoints pro naše API setkáváme se situacemi, kdy si nejsme jisti, zda psát v množném nebo jednotném čísle. Měli bychom použít podtržítka nebo pomlčky? Jak uvést ID? Pro API, které vytváří zdroj, bychom měli použít /resource/create? A mnoho dalších otázek. Pojďme se tedy ponořit hlouběji do konvencí pojmenování pro REST API. Zde se budeme zabývat:

Endpoints
Metody
Verzování

Endpoints

Začněme si projít některé konvence pojmenování REST API.

Zdroje jako podstatná jména

REST API by vám mělo umožnit manipulovat se zdrojem pomocí jedné z hlavních HTTP metod. REST URI by neměly indikovat žádné operace CRUD. Měly by odkazovat na zdroj namísto akce/slovesa. Kdykoli je to možné, používejte pouze množnou formu podstatných jmen, pokud se nejedná o singleton zdroje.

Dobré příklady:

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

Špatné příklady:

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

Hierarchie

Hierarchie mezi zdroji a sbírkami je definována použitím lomítek.

"Stejně jako u všeho v řemesle vývoje softwaru je pojmenování rozhodující pro úspěch"

Dobrý příklad:

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

Špatný příklad:

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

Pomlčky

Je široko-daleko přijímáno, že čtení pomlček ( first-name ) je jasnější a uživatelsky přívětivější než čtení podtržítek ( first_name ). Takže kdykoli REST API endpoint obsahuje více slov, je vždy lepší používat pomlčky místo podtržítek. Navíc zde existuje pohled z hlediska SEO. Doporučuje se používat pomlčky, protože to pomáhá botům snadněji identifikovat koncepty v URL. A podtržítko mezi dvěma slovy je považováno za jedno slovo, zatímco použití pomlček je považováno za dvě samostatná slova.

Dobrý příklad:

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

Špatný příklad

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

Metody

Teď víme, že bychom neměli používat slovesa v našich REST API endpoints, ale vyvstává otázka, jak pak sloveso specifikovat. Na pomoc nám přicházejí HTTP metody. HTTP metody jsou slovesa, která indikují druh operace, kterou API může provádět.

HTTP metody:

GET odpovídá operaci "Čtení" zdroje nebo sbírky.
POST odpovídá operaci "Vytvoření" zdroje nebo sbírky.
PUT odpovídá operaci "Aktualizace" zdroje nebo sbírky.
DELETE odpovídá operaci "Smazání" zdroje nebo sbírky.

Existuje celkem 39 HTTP metod, ale GET, POST, PUT a DELETE jsou nejčastěji používané a základní metody. Všechny HTTP metody a jejich případy použití budeme pokrývat v samostatném blogu.

Verzování

Vždy je lepší verzovat vaše API. Stejné adresy URL mohou být spotřebovávány bez nutnosti provádět žádné zásadní změny v REST API endpoints. API endpoints by nikdy neměly být zneplatňovány, protože by to mohlo mít nepředvídané následky pro aplikace, které je spotřebovávají.

Příklady:

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

Klíčové body

Používejte podstatná jména k reprezentaci zdrojů.
Vyhněte se používání sloves v REST API endpoints.
Nepoužívejte podtržítka (`_`) v endpointu. Místo toho použijte pomlčky (`-`).
Používejte dotazy k filtrování, třídění nebo omezení sbírky API.
Nikdy nepřidávejte přípony souborů do adres URL. Pokud chcete zadat typ obsahu, použijte hlavičku `Content-Type`.
Vždy preferujte používání malých písmen v REST API endpoints.
Neuvádějte koncová lomítka (`/`) v Rest API endpoints. Nepřidávají sémantickou hodnotu a mohou být matoucí.
Vybírejte jednoduchá jména. Pokud se to provede správně, API endpoints budou velmi snadné pro jakéhokoli vývojáře pamatovat si nebo uhodnout.