{"id":34354,"date":"2019-10-31T21:57:51","date_gmt":"2019-10-31T18:57:51","guid":{"rendered":"https:\/\/prohoster.info\/blog\/pisali-api-porvali-xml-dva\/"},"modified":"2019-10-31T21:57:51","modified_gmt":"2019-10-31T18:57:51","slug":"pisali-api-porvali-xml-dva","status":"publish","type":"post","link":"https:\/\/prohoster.info\/cs\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Psali API \u2014 roztrhali XML (dvakr\u00e1t)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Prvn\u00ed API MojeSklad se objevilo p\u0159ed 10 lety. Celou tuto dobu pracujeme na st\u00e1vaj\u00edc\u00edch verz\u00edch API a vyv\u00edj\u00edme nov\u00e9. N\u011bkolik verz\u00ed API u\u017e stihlo upadnout do zapomn\u011bn\u00ed. <\/p>\n

V tomto \u010dl\u00e1nku bude mnoho informac\u00ed: jak jsme API vytv\u00e1\u0159eli, pro\u010d je pot\u0159ebn\u00e9 pro cloudovou slu\u017ebu, co p\u0159in\u00e1\u0161\u00ed u\u017eivatel\u016fm, na jak\u00e9 p\u0159ek\u00e1\u017eky jsme narazili a co pl\u00e1nujeme d\u00e1l.
\n<\/a><\/noindex>
\nJmenuji se Oleg Alexejev oalexeev<\/a><\/noindex>, jsem technick\u00fd \u0159editel a spoluzakladatel MojeSklad. <\/p>\n

Pro\u010d vytv\u00e1\u0159et API pro slu\u017ebu<\/h2>\n

\nNa\u0161i klienti, co\u017e jsou des\u00edtky tis\u00edc podnikatel\u016f, aktivn\u011b vyu\u017e\u00edvaj\u00ed cloudov\u00e1 \u0159e\u0161en\u00ed: bankovnictv\u00ed, internetov\u00e9 obchody, skladov\u00e9 hospod\u00e1\u0159stv\u00ed, CRM. K jednomu se p\u0159ipoj\u00edte \u2014 a u\u017e je t\u011b\u017ek\u00e9 se zastavit. A u\u017e p\u00e1t\u00e1, osm\u00e1, des\u00e1t\u00e1 slu\u017eba usnad\u0148uje pr\u00e1ci podnikatel\u016f, ale u\u017eivatel\u00e9 mezi t\u011bmito cloudov\u00fdmi slu\u017ebami p\u0159en\u00e1\u0161ej\u00ed data ru\u010dn\u011b. Pr\u00e1ce se prom\u011b\u0148uje v no\u010dn\u00ed m\u016fru.<\/p>\n

O\u010dividn\u00e9 \u0159e\u0161en\u00ed \u2014 umo\u017enit u\u017eivatel\u016fm p\u0159en\u00e1\u0161et data mezi cloudov\u00fdmi slu\u017ebami. Nap\u0159\u00edklad importovat a exportovat data jako soubory, kter\u00e9 pot\u00e9 lze nahr\u00e1t do po\u017eadovan\u00e9 slu\u017eby. Soubory se obvykle p\u0159izp\u016fsobuj\u00ed form\u00e1tu ka\u017ed\u00e9 slu\u017eby. Je to v\u00edce \u010di m\u00e9n\u011b jednoduch\u00e1 ru\u010dn\u00ed pr\u00e1ce, ale se zvy\u0161uj\u00edc\u00edm se po\u010dtem t\u011bchto slu\u017eeb se jej\u00ed prov\u00e1d\u011bn\u00ed st\u00e1v\u00e1 st\u00e1le slo\u017eit\u011bj\u0161\u00ed.<\/p>\n

Proto je dal\u0161\u00edm krokem \u2014 API. S n\u00edm cloudov\u00e1 slu\u017eba t\u011b\u017e\u00ed z toho, \u017ee spojuje n\u011bkolik slu\u017eeb na jednom m\u00edst\u011b. Vznik takov\u00e9 ekosyst\u00e9my p\u0159itahuje nov\u00e9 klienty d\u00edky roz\u0161\u00ed\u0159en\u00fdm mo\u017enostem. Produkt s novou funkcionalitou se st\u00e1v\u00e1 v\u00fdhodn\u011bj\u0161\u00edm a u\u017eite\u010dn\u011bj\u0161\u00edm.<\/p>\n

Pokud vytv\u00e1\u0159\u00edte vlastn\u00ed programov\u00e9 rozhran\u00ed, p\u0159itahuje to extern\u00ed prodejce v podob\u011b program\u00e1tor\u016f, kte\u0159\u00ed se o va\u0161em produktu dozv\u00eddaj\u00ed d\u00edky API. Za\u010d\u00ednaj\u00ed budovat \u0159e\u0161en\u00ed na z\u00e1klad\u011b nab\u00edzen\u00e9ho API a vyd\u011bl\u00e1vaj\u00ed pen\u00edze na automatizaci \u00fakol\u016f sv\u00fdch klient\u016f.<\/p>\n

\u00da\u010detn\u00ed syst\u00e9m MojeSklad se zakl\u00e1d\u00e1 na jednoduch\u00fdch procesech. Hlavn\u00ed je pr\u00e1ce s prim\u00e1rn\u00edmi dokumenty, mo\u017enost prov\u00e1d\u011bt p\u0159ej\u00edmky a v\u00fddeje zbo\u017e\u00ed, z\u00edsk\u00e1vat na z\u00e1klad\u011b prim\u00e1rn\u00edch dokument\u016f zpr\u00e1vy pro byznys. Tak\u00e9 existuje p\u0159enos dat, nap\u0159\u00edklad do cloudov\u00e9ho \u00fa\u010detnictv\u00ed, a jejich z\u00edsk\u00e1v\u00e1n\u00ed z bankovn\u00edch syst\u00e9m\u016f nebo maloobchodn\u00edch m\u00edst. Pracujeme tak\u00e9 s internetov\u00fdmi obchody: z\u00edsk\u00e1v\u00e1me informace o zbo\u017e\u00ed a zas\u00edl\u00e1me \u00fadaje o z\u00e1sob\u00e1ch.<\/p>\n

\"Psali
\n<\/p>\n

Prvn\u00ed API MojeSkladu<\/h2>\n

\nB\u011bhem 10 let na\u0161eho p\u016fsoben\u00ed s API jsme z\u00edskali r\u016fzn\u00e1 spojen\u00ed, kter\u00e1 umo\u017e\u0148uj\u00ed v\u00fdm\u011bnu dat, spolupr\u00e1ci s bankami, prov\u00e1d\u011bn\u00ed plateb a vyu\u017e\u00edv\u00e1n\u00ed extern\u00ed telefonie.<\/p>\n

V prvn\u00edm roce jsme zavedli mo\u017enost exportovat jak\u00e1koliv data ve form\u00e1tu XML. U\u017eivatelsk\u00e1 rozhran\u00ed byla tehdy pro u\u017eivatele mnohem srozumiteln\u011bj\u0161\u00ed a obvykl\u00e9 dr\u017eet data offline, a ne v n\u011bjak\u00e9m cloudu, a my jim tuto mo\u017enost nab\u00edzeli. Export spou\u0161t\u011bli u\u017eivatel\u00e9 ru\u010dn\u011b z rozhran\u00ed. Tedy to je\u0161t\u011b nemohlo b\u00fdt naz\u00fdv\u00e1no API. <\/p>\n

Tehdy jsme za\u010dali spolupracovat s firmou Rusagro \u2014 ta ji\u017e pou\u017e\u00edvala \"dosp\u011blou\" ERP pro pl\u00e1nov\u00e1n\u00ed v\u00fdroby a prodeje, zat\u00edmco nakl\u00e1d\u00e1n\u00ed voz\u016f na z\u00e1vodech automatizovali v MojeSkladu. Tak se u n\u00e1s objevily prvn\u00ed z\u00e1rodky skute\u010dn\u00e9ho API: v\u00fdm\u011bna mezi na\u0161\u00edm servisem a ERP prob\u00edhala zas\u00edl\u00e1n\u00edm velk\u00e9ho souboru s daty ohledn\u011b v\u0161ech typ\u016f dokument\u016f. <\/p>\n

To byla slu\u0161n\u00e1 alternativa pro hromadnou v\u00fdm\u011bnu dat, ale spolu s dokumenty bylo nutn\u00e9 p\u0159ed\u00e1vat tak\u00e9 jejich z\u00e1vislosti: informace o produktech, partnerech a skladech. Takovou divo\u010dinu nebylo t\u011b\u017ek\u00e9 vygenerovat b\u011bhem exportu, ale p\u0159i importu bylo dost obt\u00ed\u017en\u00e9 ji zpracovat, proto\u017ee v jednom bal\u00ed\u010dku p\u0159ich\u00e1zely v\u0161echny informace: jak o nov\u00fdch dokumentech, tak o ji\u017e existuj\u00edc\u00edch.<\/p>\n

Prvn\u00ed XML API nep\u0159e\u017eilo dlouho \u2014 po dvou letech jsme za\u010dali s jeho p\u0159estavbou. Ji\u017e na za\u010d\u00e1tku jeho fungov\u00e1n\u00ed jsme ud\u011blali n\u011bkolik chyb p\u0159i stavb\u011b programov\u00e9ho rozhran\u00ed.<\/p>\n

\"Psali
\nTakto jsme vyv\u00edjeli XML API: ilustrace od jednoho z na\u0161ich architekt\u016f. Mimochodem, o\u010dek\u00e1vejte jeho \u010dl\u00e1nky.<\/i><\/p>\n

Toto jsou na\u0161e hlavn\u00ed chyby:<\/p>\n

    \n
  1. JAXB rozvr\u017een\u00ed bylo vytvo\u0159eno p\u0159\u00edmo na entity beanech. Pro komunikaci s datab\u00e1z\u00ed pou\u017e\u00edv\u00e1me Hibernate, a to stejn\u00e9 rozvr\u017een\u00ed bylo pou\u017eito na tyto beany. Tato chyba se projevila t\u00e9m\u011b\u0159 okam\u017eit\u011b: jak\u00e1koliv zm\u011bna struktury dat vedla k nutnosti urgentn\u00edho upozorn\u011bn\u00ed v\u0161ech, kdo pou\u017e\u00edvaj\u00ed API, nebo k vytvo\u0159en\u00ed z\u00e1chrann\u00fdch \u0159e\u0161en\u00ed, kter\u00e1 by zajistila kompatibilitu se star\u0161\u00ed strukturou dat.<\/li>\n
  2. API se vyvinul jako dopln\u011bk, a p\u016fvodn\u011b jsme neur\u010dili, jakou \u010d\u00e1st produktu p\u0159edstavuje. Nep\u0159em\u00fd\u0161leli jsme ani o tom, zda je API n\u011b\u010d\u00edm d\u016fle\u017eit\u00fdm, zda je pot\u0159eba zachovat zp\u011btnou kompatibilitu pro prvn\u00ed z\u00e1kazn\u00edky. V ur\u010dit\u00e9m okam\u017eiku po\u010det u\u017eivatel\u016f API \u010dinil p\u0159ibli\u017en\u011b 5 % z celkov\u00e9ho mal\u00e9ho po\u010dtu, a nev\u011bnovali jsme j\u00ed pozornost. Univerz\u00e1ln\u00ed filtrov\u00e1n\u00ed, kter\u00e9 bylo tehdy vytvo\u0159eno, vedlo k tomu, \u017ee n\u00e1s za\u010dali pou\u017e\u00edvat jako backend. Toto filtrov\u00e1n\u00ed nebylo zcela GraphQL, ale n\u011bco podobn\u00e9ho \u2013 fungovalo to skrze spoustu parametr\u016f v URL dotazu. S tak mocn\u00fdm n\u00e1strojem bylo pro u\u017eivatele t\u011b\u017ek\u00e9 se odt\u00e1hnout, a \u017e\u00e1dosti byly sm\u011brov\u00e1ny tak, \u017ee byly vys\u00edl\u00e1ny p\u0159\u00edmo z UI jejich internetov\u00fdch obchod\u016f. Situace byla nep\u0159\u00edjemn\u00fdm p\u0159ekvapen\u00edm, proto\u017ee poskytov\u00e1n\u00ed takov\u00e9 slu\u017eby by m\u011blo vy\u017eadovat jinou cenovou strukturu a zcela jin\u00fd pohled na samotn\u00e9 API jako produkt.<\/li>\n
  3. Proto\u017ee API se nevyv\u00edjelo jako hlavn\u00ed produkt, dokumentace k API byla vytv\u00e1\u0159ena a publikov\u00e1na sp\u00ed\u0161e jako zbytkov\u00fd produkt \u2013 prost\u0159ednictv\u00edm zp\u011btn\u00e9ho in\u017een\u00fdrstv\u00ed. Tato cesta se m\u016f\u017ee jevit jako pom\u011brn\u011b jednoduch\u00e1 a pohodln\u00e1, ale odporuje pr\u00e1ci podle smlouvy. To je, kdy\u017e existuje n\u011bjak\u00e1 komponenta s p\u0159ednastaven\u00fdm sch\u00e9matem pr\u00e1ce. V\u00fdvoj\u00e1\u0159 ji implementuje podle tohoto sch\u00e9matu a \u00fakolu, komponenta proch\u00e1z\u00ed testov\u00e1n\u00edm, klient dost\u00e1v\u00e1 produkt, kter\u00fd odpov\u00edd\u00e1 vizi analytika. Zp\u011btn\u00e9 in\u017een\u00fdrstv\u00ed v\u0161ak vrh\u00e1 na trh produkt, kter\u00fd je prost\u011b p\u0159\u00edtomen: s provizorn\u00edmi \u0159e\u0161en\u00edmi, podivn\u00fdmi rozhodnut\u00edmi a \u201ekola\u201c m\u00edsto pot\u0159ebn\u00e9 funk\u010dnosti. <\/li>\n
  4. Cel\u00fd tok \u017e\u00e1dost\u00ed, kter\u00fd p\u0159ich\u00e1zel p\u0159es API, mohl b\u00fdt analyzov\u00e1n maxim\u00e1ln\u011b jako log Nginxu nebo aplika\u010dn\u00edho serveru. To neumo\u017enilo vymezit odborn\u00e9 oblasti, pokud ne\u0161lo rozd\u011blit podle u\u017eivatel\u016f a odb\u011bratel\u016f. Pokud nen\u00ed mo\u017en\u00e9 regulovat registraci aplikac\u00ed nebo klient\u016f, st\u00e1v\u00e1 se anal\u00fdza situace nemo\u017enou. Tento probl\u00e9m m\u011bl pouze minim\u00e1ln\u00ed vliv na v\u00fdvoj API, v\u00edce se t\u00fdkal porozum\u011bn\u00ed jeho popt\u00e1vce a napln\u011bn\u00ed funkcionalitou.<\/li>\n<\/ol>\n

    <\/p>\n

    Pok Attempt number two: REST API<\/h2>\n

    \nV roce 2010 jsme se pokusili vybudovat syst\u00e9m v\u00fdm\u011bny s online \u00fa\u010detnictv\u00edm \u2014 BuchSoft. Nepovedlo se. B\u011bhem integrace v\u0161ak vzniklo plnohodnotn\u00e9 API: REST slu\u017eba v\u00fdm\u011bny, kde chyb\u011bly volnosti jako vol\u00e1n\u00ed operac\u00ed pomoc\u00ed RPC. Ve\u0161ker\u00e1 komunikace s API byla p\u0159evedena do standardn\u00edho re\u017eimu pro REST: v dotazu je n\u00e1zev entity a operace, kter\u00e1 s n\u00ed bude provedena, je ur\u010dena pomoc\u00ed HTTP metody. P\u0159idali jsme filtrov\u00e1n\u00ed podle okam\u017eiku aktualizace entit a u\u017eivatel\u00e9 z\u00edskali mo\u017enost vytv\u00e1\u0159et replikaci se sv\u00fdmi syst\u00e9my.<\/p>\n

    Ve stejn\u00e9m roce vzniklo API pro export skladov\u00fdch a zbo\u017eov\u00fdch z\u016fstatk\u016f. U\u017eivatel\u016fm se prost\u0159ednictv\u00edm API staly dostupn\u00e9 nejcenn\u011bj\u0161\u00ed \u010d\u00e1sti syst\u00e9mu \u2014 v\u00fdm\u011bna prim\u00e1rn\u00edch dokument\u016f a v\u00fdpo\u010dtov\u00e9 \u00fadaje o z\u016fstatc\u00edch a n\u00e1kladovosti zbo\u017e\u00ed.<\/p>\n

    V prosinci 2015 RetailCRM zve\u0159ejnil prvn\u00ed extern\u00ed knihovnu pro p\u0159\u00edstup k na\u0161emu API. Ta byla pom\u011brn\u011b aktivn\u011b pou\u017e\u00edv\u00e1na, p\u0159i\u010dem\u017e rostla popularita slu\u017eby jako celku, zat\u00ed\u017een\u00ed API rostlo rychleji ne\u017e zat\u00ed\u017een\u00ed webov\u00e9ho rozhran\u00ed. Jednou se r\u016fst prom\u011bnil v skok zat\u00ed\u017een\u00ed. <\/p>\n

    \"Psali
    \n
    \n\"Psali
    \n
    \nA tento skok, kter\u00fd ukazuje \u0161ipka vlevo, p\u0159ivedl k naprost\u00e9mu \u00fa\u017easu server, kter\u00fd obsluhuje na\u0161e API. T\u00fdden jsme zji\u0161\u0165ovali, co konkr\u00e9tn\u011b tuto z\u00e1t\u011b\u017e generuje. Uk\u00e1zalo se, \u017ee jde o tyto po\u017eadavky, kter\u00e9 se p\u0159en\u00e1\u0161ely na na\u0161e API z front u klient\u016f. V\u0161e sn\u011bdlo asi 50 klient\u016f. Tehdy jsme pochopili jednu ze sv\u00fdch chyb \u2014 \u00faplnou absenci limit\u016f. <\/p>\n

    Nakonec jsme zavedli limit na po\u010det sou\u010dasn\u00fdch po\u017eadavk\u016f. Z jednoho \u00fa\u010dtu bylo mo\u017en\u00e9 sou\u010dasn\u011b otev\u0159\u00edt maxim\u00e1ln\u011b dva po\u017eadavky. To je dostate\u010dn\u00e9 pro pr\u00e1ci v re\u017eimu replikace pro v\u00fdm\u011bnu dat v d\u00e1vkov\u00e9m re\u017eimu. Ti, kte\u0159\u00ed n\u00e1s cht\u011bli pou\u017e\u00edvat jako backend, byli od t\u00e9 doby nuceni v\u00edce dodr\u017eovat tarify, proto\u017ee zavedli ve sv\u00fdch softwarov\u00fdch prost\u0159edc\u00edch pr\u00e1ci s n\u011bkolika \u00fa\u010dty.<\/p>\n

    Ukl\u00edz\u00edme<\/h2>\n

    \nJi\u017e od roku 2014 byl z\u00e1jem o existuj\u00edc\u00ed API d\u016fle\u017eitou sou\u010d\u00e1st\u00ed podnik\u00e1n\u00ed a samo API generovalo nejv\u011bt\u0161\u00ed objem dat p\u0159i v\u00fdm\u011bn\u011b dat s klienty. V roce 2015 jsme spustili projekt na \u00fapravu API. Vybrali jsme jako form\u00e1t JSON m\u00edsto XML a za\u010dali jej stav\u011bt na z\u00e1klad\u011b vlastnost\u00ed, kter\u00e9 jsme odhalili p\u0159i realizaci p\u0159edchoz\u00ed verze:<\/p>\n

      \n
    1. Mo\u017enost spravovat verze. Verzionov\u00e1n\u00ed umo\u017e\u0148uje vyv\u00edjet novou verzi, ani\u017e by to ovlivnilo st\u00e1vaj\u00edc\u00ed aplikaci a naru\u0161ilo fungov\u00e1n\u00ed u\u017eivatel\u016f. <\/li>\n
    2. Mo\u017enost, aby u\u017eivatel vid\u011bl metadata v odpov\u011bdi, kterou dost\u00e1v\u00e1.<\/li>\n
    3. Mo\u017enost v\u00fdm\u011bny velk\u00fdch dokument\u016f. Pokud zpracov\u00e1v\u00e1me dokument s po\u010dtem polo\u017eek p\u0159es 4-5 tis\u00edc, st\u00e1v\u00e1 se to probl\u00e9mem pro server: dlouh\u00e1 transakce, dlouh\u00fd http dotaz. Vytvo\u0159ili jsme speci\u00e1ln\u00ed mechanismus, kter\u00fd umo\u017e\u0148uje aktualizovat dokument po \u010d\u00e1st\u00edch a spravovat jednotliv\u00e9 polo\u017eky tohoto dokumentu, kter\u00e9 se odes\u00edlaj\u00ed na server.<\/li>\n
    4. N\u00e1stroje pro replikaci \u2013 byly i v p\u0159edchoz\u00ed verzi.<\/li>\n
    5. Limity zat\u00ed\u017een\u00ed \u2013 jako d\u011bdictv\u00ed chyb, na kter\u00e9 jsme narazili v p\u0159edchoz\u00ed verzi. Zavedli jsme limity na po\u010det dotaz\u016f v ur\u010dit\u00e9m \u010dasov\u00e9m obdob\u00ed, po\u010det paraleln\u00edch dotaz\u016f a dotaz\u016f z jedn\u00e9 ip adresy.<\/li>\n<\/ol>\n

      \nOd t\u00e9 doby jsme vydali dv\u011b minoritn\u00ed verze API a spustili n\u011bkolik specializovan\u00fdch API, ale celkov\u00fd p\u0159\u00edstup z\u016fstal beze zm\u011bn. Aktualizovan\u00fd form\u00e1t v\u00fdm\u011bny a nov\u00e1 architektura umo\u017enily opravit nedostatky v API mnohem rychleji.<\/p>\n

      API MojeSklady dnes<\/h2>\n

      \nDnes API MojeSklady \u0159e\u0161\u00ed mnoho \u00fakol\u016f:<\/p>\n