Při shánění materiálů jsem dnes narazil na REST API k účetnímu systému WinStrom. A je opravdu pěkné. Ale má i své mouchy.
Samozřejmě jako transportní protokol použili HTTP. Podporují HTTPS a HttpBasic - což ve spolupráci s přístupovými právy dostatečně zabezpečuje bezpečnost dat. Používají klasické operace GET, POST, PUT a DELETE (PUT a POST zeqivaletnili, což ale samozřejmě není nic proti RESTóznosti API), používají celkem hojně HTTP status.
URL jsou taky HTTP. Celkem logicky nejsou neprůhledná - mají svoji logiku.
Pro práci s kolekcí jedné evidence to jsou:
/ID.firmy/typevidence{/[reports|properties|relations|filtr]}
a pro práci s konkrétní položkou
/ID.firmy/typevidence/ID.záznamu{.formát}{/podevidence} (tady si nejsem jist, jestli ten formát je povinný nebo není, IMHO by být neměl, ale z docky plyne, že je)
Co se týká RESTových operací, tak si vystačí se čtyřmi - klasický CRUD.
CREATE se volá na kolekci. Návratová hodnota je buď neúspěch nebo úspěch. Úspěch v sobě obsahuje identifikátor vytvořeného zdroje.
UPDATE se volá na konkrétní zdroj - tam jdou nová data, zpátky status operace.
DELETE je klasický - jenom jsem nenašel, na co vše se dá volat.
GET je pěkný. Je sice parametrizovaný, ale parametry lze rozdělit do tří kategorií - stránkování a řazení, přidání metadat a (s tím mám kapku problém) XPath na výsledek, jestliže je ve formátu XML (z důvodu omezení přenášených dat)
Až doposud popis a chvála. Teď ale vady na kráse:
- XPath jsem už zmínil, ale to není zas takový problém
- Operace CREATE vrátí identifikátor záznamu, nikoli URL, takže URL si uživatel musí sám poskládat, a to je samozřejmě proti RESTu
- GETové URL obsahuje formát výsledku - zde by bylo na místě použít parametr v QUERY_STRING, ale chápu, že MS Explorer by si s tím nemusel poradit (alespoň v dřevních dobách používal MSIE příponu ke stanovení content-type :-) )
- A na závěr to nejhorší. PARAMETR filtr pro fitrování dat na kolekci není použit jako parametr, nýbrž jako součást identifikátoru, což je VYSOCE nehezké. Cpát přímo do URL ořezanou obdobu SQL (viz syntaxe Filtrování záznamů) mi přijde více než nechutné.
Příspěvky
4 komentáře:
Zdravím a děkuji za připomínky.
Pokusím se reagovat:
- co je za problém s XPath?
- s URL souhlasím. Asi bychom jej mohli sestavit.
- formát výsledku je možné určit buď pomocí hlavičky Accept a nebo jako součást URL. Formát v URL není povinný. Pokud je uveden, má přednost před hlavičkou Accept. Aktualizoval jsem dokumentaci.
- k filtraci: aktuálně zvažujeme podporu formátu i pro styl z Ruby. Tj. podmínka bude přidána i jako GET parametry. Osobně považuji za ekvivalentní tyto formy zápisu:
/faktura-vydana/(stavUhrK='uhrazeno%27)
/faktura-vydana/?filter=stavUhrK=%3d%27uhrazeno%27
Důvodem rozšíření bude kompatibilita s jinými systémy.
Nicméně jsem rád, že REST API zaujalo.
Petr Ferschmann
WinStrom s.r.o.
Zdravím,
ještě jsem si vzpomněl: pokud se vytvoří nový záznam, je odpovědí 200 Created a v Location je URL nově vytvořeného záznamu. Odpovědí je XML, které obsahuje pouze ID.
Takže vlastně druhý bod je splněný také :-)
Accept je přesně to, co se mi líbí. Ani jsem nedoufal, že by to někdo kromě nás pár odvážlivců v R&D v Systinetu použilo.
K filtraci - včera jsem k tomu napsal jeden maxiblogpost, na komentář by toho bylo kupa.
PS: Předpokládám, že se jedná o 201 Created ;-)
Jo a problém s XPath - asi takto: pokud je to chápáno a zacházeno jako s novou operací EXTRACT nad tímtéž zdrojem, je to v pořádku. Pokud se s tím zachází jako s parametrem GETu, pak se dostáváme do kolize, protože parametr výrazně mění logiku věci - jednou je to tentýž zdroj při identitě, jednou je to jedna položka faktury, jednou SPZ auta,...
Okomentovat