REST API - CRUD - Jurij Starynec

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