CRUD vzor#

Všechny zdroje sdílejí tutéž sadu akcí.

🔴 Parametry se posílají v adrese#

Tělo požadavku se u CRUD akcí nečte vůbec

Ani formulářové, ani JSON. Všechno — včetně dat k uložení — jde do dotazu v adrese, v zápisu polí jazyka PHP: data[title]=…&data[category][id]=3.

Jediná výjimka jsou přihlašovací endpointy, které naopak čtou formulářové tělo a JSON nepřečtou.

Metoda HTTP nerozhoduje#

GET /api/…/delete?id=5 skutečně smaže

Akce se určuje z adresy, ne z metody. Nedávejte adresy API do předběžného načítání ani nikam, kde je projde robot.

Akce#

Akce	K čemu
`get`	jeden záznam podle `id`
`get-by`	jeden záznam podle filtru
`get-all`	výpis
`save`	vložení i úprava
`update-columns`	změna vybraných polí
`delete`	smazání
`delete-all`	smazání podle filtru

Parametry čtení#

Parametr	Význam
`id`	identifikátor
`filters`	filtry, viz níže
`orderBys`	řazení
`offset`, `limit`	stránkování
`columns`	zúžení vrácených polí
`includes`	načtení vazeb
`computeTotalCount`	`1` spočítá celkový počet

Řazení#

orderBys[created]=1     vzestupně
orderBys[created]=0     sestupně
orderBys[category.name]=1

Směr je pravdivostní hodnota, ne asc / desc

orderBys[name]=desc je neprázdný řetězec, tedy pravda — seřadí vzestupně. Používejte 1 a 0.

Vazby#

includes[]=translations&includes[]=user.roles

includes=* natáhne všechny vazby

Snadná cesta k obrovské odpovědi a pomalému dotazu. Vyjmenujte, co potřebujete.

Filtry#

Filtr je trojice [typ, pole, hodnota]:

?filters[0][0]=equal&filters[0][1]=activated&filters[0][2]=1
&filters[1][0]=like&filters[1][1]=title&filters[1][2]=notebook&filters[1][matchType]=both
&filters[2][0]=in&filters[2][1]=id&filters[2][2][]=1&filters[2][2][]=2

Filtry se skládají operací a zároveň.

Typ	Doplňkové klíče
`equal`, `notEqual`
`like`, `notLike`	`matchType`: `both`, `start`, `end`
`in`, `notIn`
`isNull`, `isNotNull`
`between`	`from`, `to`
`range`	`inclusive`
`greaterThan`, `greaterOrEqual`	zkratky `gt`, `gte`
`lessThan`, `lessOrEqual`	zkratky `lt`, `lte`
`comparison`	`operator`
`date`, `dateBetween`, `dateAfter`, `dateBefore`	`operator`, `format`
`group`, `or`, `and`	`filters`, `logic`
`fulltext`	`mode`, `minScore`

Neznámý typ filtru vrátí chybu 500

Ne validační hlášku. Překlep v názvu filtru shodí požadavek.

Uložení#

Jeden endpoint pro vložení i úpravu. Rozlišuje se přítomností data[id].

/api/blog/article/save?data[title]=Novinka&data[category][id]=3

Část dat se tiše zahodí

Odpověď hlásí úspěch, ale hodnota se neuloží. Zahazuje se:

meta — u většiny zdrojů celé,
pole označená jako jen pro čtení zvenčí (přes čtyřicet napříč systémem),
pole vyhrazená administrátorům,
vnořené kolekce, které daný zdroj nepovoluje.

Jediná stopa je v logu na serveru. Po zápisu si data načtěte znovu a zkontrolujte.

Vlastníka dosazuje server

Při vkládání se vlastník bere z přihlášení. Poslaný identifikátor uživatele se ignoruje.

Prázdná data vrátí kód 602.

Změna vybraných polí#

/api/eshop/order/update-columns?ids[]=5&values[stav]=2

Zvenčí to u většiny zdrojů nefunguje

Seznam povolených sloupců je výchozím nastavením prázdný, takže volání skončí kódem 607. Funguje jen u sloupců, které mají výslovnou výjimku.

Žádný částečný zápis

Stačí jeden nepovolený sloupec a padá celé volání.

Mazání#

/api/bazaar/watchdog/delete?id=123
/api/bazaar/watchdog/delete?id[]=1&id[]=2

Hromadné mazání neprojde kontrolou vlastnictví

Pro roli vlastníka je vždy zamítnuté.

Stromové zdroje#

Kategorie a menu nabízejí navíc move-up, move-down, move-subtree, move-subtree-to, insert-tree-node a delete-node.

delete-node smaže celý podstrom

Ne jen uzel.

Události#

register-event zvýší počítadlo o jedna:

/api/comcat/advert/register-event?ids[]=1&property=views

Povolené názvy počítadel jsou omezené seznamem.

🔴 Řada funkcí není zvenčí dostupná#

Zdroj může existovat a přesto vracet 404

Systém obsahuje mnoho operací, které používá jen web zevnitř a které nemají HTTP obal. Patří sem košík, dokončení objednávky, přehledy „moje“, dostupnost a aktuální ceny.

Poznáte to tak, že akce vrátí 404 s HTML, přestože zdroj i oprávnění existují.