V tomto díle zmíním důležité prvky, které RESTful api mělo obsahovat. Podíváme se na názorné příklady request/response, pojmenování, jaké jsou metody a verzování
URL
Jeden z největších problémů zkoumaných v IT odvětví, který se stále řeší je pojmenování. V momentě, kdy v programování něco pojmenováváte jsou nejdůležitější dvě věci. První je, co pojmenováváte a druhá je pro koho. V ostatních případech vyhrává selský rozum a jednoduchost. Na první pohled by mělo být zřejmé, co máte na mysli. Při psaní endpointu používejte angličtinu a množné číslo. Proč? Protože tím nic nekomplikujete. Nemusíte řešit jednotné a množné číslo, a ať už děláte GET, POST, PUT tak používáte stejnou url adresu.
Takto byste mohli strukturovat vaše api:
https://<domain>/<contex>/<version>/<resource>
- <domain> je vaše doména, například www.rychlakola.cz
- <contex> o jakou doménu se jedná, kola, knihy, výdej zboží, logistika
- <version> o jakou verzi api se jedná
- <resource> je zdroj, který budete volat, například /books/1
Metody
Rest nám poskytuje rozhrání pro snadnou identifikaci operace. Pro CRUD jsou v RESTu definované metody (CRUD – Create, Read, Update, Delete). Úplný výpis je zde. Představte si, že máme api na databázi knih. Api nám poskytuje informace o knihách, možnost vytvářet nové a upravovat stávající. Celá komunikace bude probíhat bez autorizace přes protokol HTTP/1.1. Existuje verze HTTP/2, která je mnohem lepší a řeší nedostatky předchozí verze.
POST
POST se používá pro posílání dat na server. Takový request musí obsahovat hlavičku ‘Content-Type’. V REST api se využívá pro vytvoření nového prvku. V našem případě budeme chtít na api vytvořit novou knihu. V responsu byste měli dostat vytvořený objekt a odkaz (link na něj). V requestu je nn -> kde n je interpretováno jako číslo, <url> je vaše doména.
HTTP request
POST /books HTTP/1.1
Host: https://<url>
Content-Type: application/json
Content-Length: nn
{
"name": "My best book ever",
"author": "Johny Blavolta"
}
HTTP response
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Date: Mon, 01 Apr 2019 16:42:37 GMT
Server: nginx
{
"link": "/books/1"
"book": {
"id": 1
"name": "My best book ever",
"author": "Johny Blavolta"
}
}
Request má body | Ano |
Úspěšný request má body | Ano |
Bezpečný | Ne |
Idempotent (nejde přeložit) | Ne |
Cache | Neměla by |
Povolený v HTML formulářích | Ano |
GET – jeden prvek
Nyní máme vytvořenou novou knihu. Chtěli bychom si knihu s id 1 získat. Metoda GET pouze vrací data.
HTTP request
GET /books/1 HTTP/1.1
Host: https://<url>
HTTP response
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Date: Mon, 01 Apr 2019 16:42:37 GMT
Server: nginx
{
"link": "/books/1
"book": {
"id": 1
"name": "My best book ever",
"author": "Johny Blavolta"
}
}
GET – všechny prvky
HTTP request
GET /books HTTP/1.1
Host: https://<url>
HTTP response
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Date: Mon, 01 Apr 2019 16:42:37 GMT
Server: nginx
{
"items": [
{
"link": "/books/1"
"id": 1
"name": "My best book ever",
"author": "Johny Blavolta"
}
],
"count": 1,
"limit": 10,
"pagination": {
"actual": 1,
"first": "/books?page=1",
"last": "/books?page=1"
}
}
Všimněte si, že všechny prvky jsou podřazené atributu “items“. Někdy se také objevuje jako “data“. Pak je tam atribut “count“, který informuje o počtu prvku v atributu “items“. Prvek “limit” nám udává maximální počet prvků, které chceme posílat v atributu “items“. O “limit“, “offset” a sortování si povíme více v dalších dílech. Atribut “actual” nás informuje, na které jsme stránce, také se používá jako “point“. Kdybychom chtěl listovat mezi knihami, atributy “actual“, “first” a “last” pro nás můžou být velmi užitečný nástroj. Můžeme také přidát atribut “next” pro další množinu dat.
Request má body | Ne |
Úspěšný request má body | Ano |
Bezpečný | Ano |
Idempotent (nejde přeložit) | Ano |
Cache | Ano |
Povolený v HTML formulářích | Ano |
PATCH
Pokud bychom chtěli u vytvořené knihy změnit uložené hodnoty použijme metodu PATCH. Tato metoda může měnit jeden nebo více atributu. Pozor na metodu PUT. Tu bychom použili v případě nahrazení starého objektu novým. Kdybychom poslali pouze jeden atribut, všechny ostatní budou prázdné. PATCH mění pouze poslaný atribut, všechny ostatní nechává nedotčené.
HTTP request
PATCH /books/1 HTTP/1.1
Host: https://<url>
Content-Type: application/json
Content-Length: nn
{
"name": "My the best book ever",
}
HTTP response
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Date: Mon, 01 Apr 2019 16:42:37 GMT
Server: nginx
{
"link": "/books/1"
"book": {
"id": 1
"name": "My the best book ever",
"author": "Johny Blavolta"
}
}
Request má body | Ano |
Úspěšný request má body | Ano |
Bezpečný | Ne |
Idempotent (nejde přeložit) | Ne |
Cache | Ne |
Povolený v HTML formulářích | Ne |
DELETE
Metoda DELETE nám smaže specifickou věc, v našem případě to bude kniha.
HTTP request
DELETE /books/1 HTTP/1.1
HTTP response
HTTP/1.1 200 OK
Request má body | Může |
Úspěšný request má body | Může |
Bezpečný | Ne |
Idempotent (nejde přeložit) | Ano |
Cache | Ne |
Povolený v HTML formulářích | Ne |
Verzování
Rozlišujeme majoritní a minoritní. Majoritní verze se objevuje v url adrese. Jedná se o velké změny. Minoritní byste měli posílat v hlavičce, jedná se o drobné změny, například nový atribut.
https://<domain>/<contex>/<version>/<resource> -> majoritní (v1, v2 …)
Accept-Version: 12 -> v hlavičce minoritní
V případě, kterých koli dotazů nebo námětu, kontaktujte mě na twitteru @jurij_starynec