h1. XPartial

Server standardně vrací úplnou reprezentaci požadovaného zdroje, tedy se všemi elementy, které jsou pro něj definované. Ty ovšem mohou obsahovat mnoho elementů, které klient aktuálně nevyužije, ale musí vynaložit přenosovou kapacitu a výpočetní výkon pro jejich zpracování. V případě serverových aplikací, které mají k dispozici dostatečný výkon a využívají HTTP(Hypertext Transfer Protocol) cache, to většinou nikterak nevadí, ale u lehkých aplikací, např. v JavaScriptu běžících ve webovém prohlížeči, to může představovat nezanedbatelnou zátěž.

Právě pro tento typ aplikací byl vyvinut XPartial, filtr aplikující restriktivní projekci nad výstupním dokumentem. XPartial vám umožní u každého GET zdroje určit, které elementy chcete zahrnout do výstupu, a to pomocí jednoduché syntaxe inspirované XPath. Požadované elementy se zapisují pomocí XPartial výrazu do URL parametru [[URLParameters#fields|fields]]. 

Příklad: https://kosapi.fit.cvut.cz/api/3/courses/MI-MDW?fields=id,content(code,completion,name)

Vrátí dokument obsahující pouze elementy @/entry/id, /entry/content/code, /entry/content/completion, /entry/content/name@ a všechny jejich předky po cestě ke kořenovému elementu @entry@. Ekvivalentně lze zapsat také jako @fields=id,content/code,content/completion,content/name@.


h2. Syntaxe

Formát XPartial výrazu je založen na syntaxi XPath a je kompatibilní se syntaxí "Partial response":http://code.google.com/intl/cs/apis/gdata/docs/2.0/reference.html#PartialResponse "Google Data protokolu":http://code.google.com/intl/cs/apis/gdata/, ovšem implementuje jen jeho podmnožinu.

* Cesty všech elementů jsou relativní vůči kořenovému elementu.
* Názvy elementů a cesty se oddělují čárkami, např. @updated,content/name@.
* Cesta k zanořenému elementu se skládá z po sobě jdoucích elementů oddělených lomítkem, např. @entry/content/name@.
* Zápis více zanořených elementů na stejné úrovni lze zkrátit pomocí podvýběru mezi kulatými závorkami ( ), např. @content(name,code)@. Toto lze libovolně zanořovat a kombinovat, např. @entry(content/name,content(code,range))@.
* Výběr pouze těch elementů, které obsahují požadovaný/é atribut/y, se zapisuje jako @element[@atribut='hodnota']@, např. @name[@lang='cs']@. Mezi [ ] lze zapsat více podmínek oddělených čárkami, např. @name[@lang='cs',@type='xml']@. 


h2. Pár slov o implementaci

Implementace se skládá z parseru XPartial výrazu a SAX(Simple API for XML) filtru, který je zařazen na výstupu služby, příp. před generátorem cílové datové reprezentace. Tady je nutné si uvědomit, že projekce se aplikuje až po zpracování celého požadavku, tedy až po načtení dat z databáze (či databázové cache) a jejich zpracování. Není proto vhodné ho nadužívat pro složitější filtrování dat, které lze dosáhnout jinými prostředky (např. pomocí [[RSQL]] dotazu). Jelikož _známe své lidi_, raději jsem možnosti XPartial cíleně omezil, aby ho nebylo možné nadužívat nežádoucím způsobem.