Bonusové podcasty na Pickey

REST API – CRUD

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á bodyAno
Úspěšný request má bodyAno
BezpečnýNe
Idempotent (nejde přeložit)Ne
CacheNeměla by
Povolený v HTML formuláříchAno

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á bodyNe
Úspěšný request má bodyAno
BezpečnýAno
Idempotent (nejde přeložit)Ano
CacheAno
Povolený v HTML formuláříchAno

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á bodyAno
Úspěšný request má bodyAno
BezpečnýNe
Idempotent (nejde přeložit)Ne
CacheNe
Povolený v HTML formuláříchNe

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á bodyMůže
Úspěšný request má bodyMůže
BezpečnýNe
Idempotent (nejde přeložit)Ano
CacheNe
Povolený v HTML formuláříchNe

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