{"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\/sk\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"P\u00edsali API - roztrhli XML (dva)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Prv\u00fd API MojeSkladu sa objavil pred 10 rokmi. Po cel\u00e9 toto obdobie pracujeme na existuj\u00facich verzi\u00e1ch API a vyv\u00edjame nov\u00e9. A nieko\u013eko verzi\u00ed API u\u017e stihlo skon\u010di\u0165 v zabudnut\u00ed. <\/p>\n

V tomto \u010dl\u00e1nku bude ve\u013ea vec\u00ed: ako sme vytvorili API, pre\u010do je potrebn\u00e9 pre cloudov\u00fa slu\u017ebu, \u010do prin\u00e1\u0161a pou\u017e\u00edvate\u013eom, na ak\u00e9 probl\u00e9my sme narazili a \u010do chceme robi\u0165 \u010falej.
\n<\/a><\/noindex>
\nVol\u00e1m sa Oleg Alexejev oalexeev<\/a><\/noindex>, som technick\u00fd riadite\u013e a spoluzakladate\u013e MojeSkladu. <\/p>\n

Pre\u010do robi\u0165 API pre slu\u017ebu<\/h2>\n

\nNa\u0161i klienti, a to s\u00fa desiatky tis\u00edc podnikate\u013eov, akt\u00edvne pou\u017e\u00edvaj\u00fa cloudov\u00e9 rie\u0161enia: bankovn\u00edctvo, internetov\u00e9 obchody, evidovanie tovaru, CRM. Akon\u00e1hle sa pripoj\u00edte k jedn\u00e9mu, \u0165a\u017eko sa zastav\u00edte. A u\u017e je tu piata, \u00f4sma, desiata slu\u017eba, ktor\u00e1 u\u013eah\u010duje pr\u00e1cu podnikate\u013eov, ale d\u00e1ta medzi t\u00fdmito cloudov\u00fdmi slu\u017ebami musia pou\u017e\u00edvatelia pren\u00e1\u0161a\u0165 manu\u00e1lne. Pr\u00e1ca sa men\u00ed na no\u010dn\u00fa moru.<\/p>\n

Zjavn\u00e9 rie\u0161enie \u2014 da\u0165 pou\u017e\u00edvate\u013eom mo\u017enos\u0165 pren\u00e1\u0161a\u0165 d\u00e1ta medzi cloudov\u00fdmi slu\u017ebami. Napr\u00edklad importova\u0165 a exportova\u0165 d\u00e1ta ako s\u00fabory, ktor\u00e9 je mo\u017en\u00e9 n\u00e1sledne nahra\u0165 do po\u017eadovanej slu\u017eby. S\u00fabory sa zvy\u010dajne upravuj\u00fa pod\u013ea form\u00e1tu ka\u017edej slu\u017eby. To je viac-menej jednoduch\u00e1 manu\u00e1lna pr\u00e1ca, ale s rastom po\u010dtu t\u00fdchto slu\u017eieb sa to st\u00e1va \u010doraz zlo\u017eitej\u0161\u00edm.<\/p>\n

Preto \u010fal\u0161\u00ed krok \u2014 API. S n\u00edm cloudov\u00e1 slu\u017eba vyhr\u00e1va t\u00fdm, \u017ee sp\u00e1ja nieko\u013eko slu\u017eieb na jednom mieste. Vznik takej ekosyst\u00e9my pri\u0165ahuje nov\u00fdch klientov prostredn\u00edctvom dodato\u010dn\u00fdch mo\u017enost\u00ed. Produkt s nov\u00fdmi funkciami sa st\u00e1va v\u00fdhodnej\u0161\u00edm a u\u017eito\u010dnej\u0161\u00edm.<\/p>\n

Ak vytvor\u00edte vlastn\u00e9 programov\u00e9 rozhrania, pri\u0165ahuje to nez\u00e1visl\u00fdch predajcov v podobe program\u00e1torov, ktor\u00ed poznaj\u00fa v\u00e1\u0161 produkt v\u010faka API. Za\u010d\u00ednaj\u00fa budova\u0165 rie\u0161enia na z\u00e1klade pon\u00faknut\u00e9ho API a zar\u00e1baj\u00fa peniaze na automatiz\u00e1cii \u00faloh svojich klientov.<\/p>\n

Eviden\u010dn\u00fd syst\u00e9m MojeSkladu je zalo\u017een\u00fd na jednoduch\u00fdch procesoch. Hlavn\u00e9 je pracova\u0165 s prim\u00e1rnymi dokumentmi, ma\u0165 mo\u017enos\u0165 realizova\u0165 prijatie a odoslanie tovaru, z\u00edskava\u0165 na z\u00e1klade prim\u00e1rnych dokumentov spr\u00e1vy pre podnik. Taktie\u017e m\u00e1me prenos d\u00e1t, napr\u00edklad do cloudov\u00e9ho \u00fa\u010dtovn\u00edctva, a ich prij\u00edmanie z bankov\u00fdch syst\u00e9mov alebo maloobchodn\u00fdch miest. \u010ealej pracujeme s internetov\u00fdmi obchodmi: z\u00edskavame inform\u00e1cie o tovaroch a zasielame d\u00e1ta o z\u00e1sob\u00e1ch.<\/p>\n

\"P\u00edsali
\n<\/p>\n

Prv\u00fd API MojeSkladu<\/h2>\n

\nPo desa\u0165ro\u010dnej pr\u00e1ci MojeSkladu s API sme nadobudli r\u00f4zne integr\u00e1cie, ktor\u00e9 umo\u017e\u0148uj\u00fa v\u00fdmenu \u00fadajov, pr\u00e1cu s bankami, vykon\u00e1vanie platieb a vyu\u017e\u00edvanie extern\u00fdch telef\u00f3nnych slu\u017eieb.<\/p>\n

V prvom roku sme umo\u017enili exportova\u0165 ak\u00e9ko\u013evek \u00fadaje vo form\u00e1te XML. Vtedy bolo pre pou\u017e\u00edvate\u013eov ove\u013ea zrozumite\u013enej\u0161ie a zvy\u010dajnej\u0161ie ma\u0165 \u00fadaje v offline re\u017eime, ne\u017e v nejakom oblaku, a my sme im to poskytli. Export sa sp\u00fa\u0161\u0165al ru\u010dn\u00fdm exportom z rozhrania. Tak\u017ee API sa e\u0161te nedalo nazva\u0165. <\/p>\n

V tom \u010dase sme za\u010dali spolupracova\u0165 so spolo\u010dnos\u0165ou Rusagro \u2014 u\u017e pou\u017e\u00edvali \"dospel\u00fa\" ERP na pl\u00e1novanie v\u00fdroby a predaja, zatia\u013e \u010do nahr\u00e1vanie vag\u00f3nov v tov\u00e1r\u0148ach automatizovali v MojeSklade. Tak sme dostali prv\u00e9 z\u00e1klady skuto\u010dn\u00e9ho API: v\u00fdmena medzi na\u0161ou slu\u017ebou a ERP prebiehala zasielan\u00edm ve\u013ek\u00e9ho s\u00faboru s \u00fadajmi o v\u0161etk\u00fdch typoch dokumentov. <\/p>\n

To bol celkom dobr\u00fd variant pre d\u00e1vkov\u00fa v\u00fdmenu \u00fadajov, ale spolu s dokumentmi bolo potrebn\u00e9 pren\u00e1\u0161a\u0165 aj ich z\u00e1vislosti: inform\u00e1cie o tovaroch, obchodn\u00fdch partneroch a skladoch. Tak\u00fato zmes nie je \u0165a\u017ek\u00e9 vygenerova\u0165 pri exporte, ale dos\u0165 \u0165a\u017ek\u00e9 ju roztriedi\u0165 pri importe, preto\u017ee v jednom bal\u00edku prich\u00e1dzaj\u00fa v\u0161etky inform\u00e1cie: a o nov\u00fdch dokumentoch, aj o u\u017e existuj\u00facich.<\/p>\n

Prv\u00fd XML API nevydr\u017eal dlho \u2014 po dvoch rokoch sme za\u010dali s jeho prestavbou. U\u017e na za\u010diatku jeho fungovania sme urobili nieko\u013eko ch\u00fdb pri vytv\u00e1ran\u00ed programov\u00e9ho rozhrania.<\/p>\n

\"P\u00edsali
\nAko sa robilo XML API: ilustr\u00e1cia od jedn\u00e9ho z na\u0161ich architektov. Mimochodom, \u010dakajte jeho \u010dl\u00e1nky.<\/i><\/p>\n

Tu s\u00fa na\u0161e hlavn\u00e9 chyby:<\/p>\n

    \n
  1. JAXB-ozna\u010denie bolo vykonan\u00e9 priamo na entity beans. Na komunik\u00e1ciu s datab\u00e1zou pou\u017e\u00edvame Hibernate, a na tie ist\u00e9 b\u00e1ny bolo vykonan\u00e9 JAXB-ozna\u010denie. T\u00e1to chyba sa objavila takmer okam\u017eite: ak\u00e9ko\u013evek aktualiz\u00e1cie \u0161trukt\u00fary \u00fadajov viedli k potrebe naliehavo informova\u0165 v\u0161etk\u00fdch, ktor\u00ed pou\u017e\u00edvaj\u00fa API, alebo k vytvoreniu z\u00e1plat, ktor\u00e9 by zabezpe\u010dili kompatibilitu s predch\u00e1dzaj\u00facou \u0161trukt\u00farou \u00fadajov.<\/li>\n
  2. API sa vyvinul ako ur\u010dit\u00e1 pr\u00eddavn\u00e1 s\u00fa\u010das\u0165, a p\u00f4vodne sme nedefinovali, ak\u00fa \u010das\u0165 produktu predstavuje. Ani sme neuva\u017eovali o tom, \u010di je API nie\u010d\u00edm d\u00f4le\u017eit\u00fdm, \u010di by sme mali udr\u017eiava\u0165 sp\u00e4tn\u00fa kompatibilitu pre jeho prv\u00fdch pou\u017e\u00edvate\u013eov. V ur\u010ditom okamihu predstavovalo mno\u017estvo pou\u017e\u00edvate\u013eov API pribli\u017ene 5 % z celkov\u00e9ho mal\u00e9ho po\u010dtu, a nevenovali sme im pozornos\u0165. Vytvoren\u00e1 univerz\u00e1lna filtr\u00e1cia viedla k tomu, \u017ee sme boli vy\u017e\u00edvan\u00ed ako backend. T\u00e1to filtr\u00e1cia rozhodne nebola GraphQL, ale nie\u010do podobn\u00e9 \u2014 fungovala cez mno\u017estvo parametrov v dotazovom re\u0165azci. S takou mocnou pom\u00f4ckou bolo pre pou\u017e\u00edvate\u013eov \u0165a\u017ek\u00e9 sa udr\u017ea\u0165, a n\u00e1s prepojili tak, \u017ee dotazy boli odosielan\u00e9 priamo z UI ich internetov\u00fdch obchodov. Situ\u00e1cia sa stala nepr\u00edjemn\u00fdm prekvapen\u00edm, preto\u017ee poskytovanie takejto slu\u017eby by malo vy\u017eadova\u0165 in\u00e9 tarifn\u00e9 podmienky a v\u00f4bec in\u00e9 pochopenie samotn\u00e9ho API ako produktu.<\/li>\n
  3. Ke\u010f\u017ee API sa nevyv\u00edjalo ako hlavn\u00fd produkt, dokument\u00e1cia k API sa tvorila a publikovala len okrajovo \u2014 prostredn\u00edctvom reverzn\u00e9ho in\u017einierstva. Tak\u00fdto pr\u00edstup sa zd\u00e1 by\u0165 dos\u0165 jednoduch\u00fd a praktick\u00fd, ale je v rozpore s pr\u00e1cou na zmluve. To je vtedy, ke\u010f existuje nejak\u00e1 s\u00fa\u010das\u0165 s prednastaven\u00fdm sp\u00f4sobom fungovania. V\u00fdvoj\u00e1r ju implementuje pod\u013ea tejto sch\u00e9my a \u00falohy, s\u00fa\u010das\u0165 sa testuje, z\u00e1kazn\u00edk dost\u00e1va produkt, ktor\u00fd zodpoved\u00e1 predstave analytika. Reverzn\u00e9 in\u017einierstvo v\u0161ak vyhadzuje na trh produkt, ktor\u00fd jednoducho existuje: s obmedzeniami, zvl\u00e1\u0161tnymi rie\u0161eniami a 'bicyklami' namiesto potrebnej funkcionality. <\/li>\n
  4. Cel\u00fd pr\u00fad \u017eiadost\u00ed prich\u00e1dzaj\u00faci cez API bolo mo\u017en\u00e9 analyzova\u0165 maxim\u00e1lne ako log Nginx alebo aplika\u010dn\u00e9ho servera. To neumo\u017e\u0148ovalo vy\u010dleni\u0165 predmetn\u00e9 oblasti, maxim\u00e1lne ich rozdeli\u0165 pod\u013ea pou\u017e\u00edvate\u013eov a predplatite\u013eov. Ak nie je mo\u017en\u00e9 regulova\u0165 registr\u00e1ciu aplik\u00e1cie alebo klientov, anal\u00fdza situ\u00e1cie sa st\u00e1va nemo\u017enou. Tento probl\u00e9m najmenej ovplyvnil v\u00fdvoj API, viac sa t\u00fdkal pochopenia jeho dopytu a naplnenia funk\u010dnost\u00ed.<\/li>\n<\/ol>\n

    <\/p>\n

    Pok attempt \u010d\u00edslo dva: REST API<\/h2>\n

    \nV roku 2010 sme sa sna\u017eili vybudova\u0165 syst\u00e9m v\u00fdmeny s online \u00fa\u010dtovn\u00edctvom \u2013 BuchSoftom. Ne\u00faspe\u0161ne. V procese integr\u00e1cie sa v\u0161ak objavil plnohodnotn\u00fd API: REST slu\u017eba v\u00fdmeny, kde ch\u00fdbali v\u00fdnimky ako volania oper\u00e1ci\u00ed v podobe RPC. V\u0161etka komunik\u00e1cia s API bola zredukovan\u00e1 na \u0161tandardn\u00fd sp\u00f4sob pre REST: v dopyte je n\u00e1zov entity a oper\u00e1cia, ktor\u00e1 sa s \u0148ou vykon\u00e1va, je ur\u010den\u00e1 pomocou http-met\u00f3dy. Pridali sme filtrovanie pod\u013ea okamihu aktualiz\u00e1cie ent\u00edt a u\u017e\u00edvatelia dostali mo\u017enos\u0165 nastavi\u0165 replik\u00e1ciu so svojimi syst\u00e9mami.<\/p>\n

    V tom istom roku sa objavil API na export skladov\u00fdch a tovarov\u00fdch zostatkov. Pre u\u017e\u00edvate\u013eov sa prostredn\u00edctvom API stali dostupn\u00e9 najcennej\u0161ie \u010dasti syst\u00e9mu \u2013 v\u00fdmena prim\u00e1rnych dokumentov a v\u00fdpo\u010dtov\u00e9 \u00fadaje o zostatkoch a n\u00e1kladoch na tovary.<\/p>\n

    V decembri 2015 RetailCRM zverejnil prv\u00fa extern\u00fa kni\u017enicu na pr\u00edstup k n\u00e1\u0161mu API. Stala sa dos\u0165 akt\u00edvne pou\u017e\u00edvanou, pri\u010dom rastla popularita slu\u017eby ako celku, z\u00e1\u0165a\u017e na API r\u00e1stla r\u00fdchlej\u0161ie ako z\u00e1\u0165a\u017e na webovom rozhran\u00ed. Raz sa rast premenil na skok z\u00e1\u0165a\u017ee. <\/p>\n

    \"P\u00edsali
    \n
    \n\"P\u00edsali
    \n
    \nA tento skok, na ktor\u00fd ukazuje \u0161\u00edpka v\u013eavo, priviedol server obsluhuj\u00faci na\u0161e API do \u00fapln\u00e9ho \u00fa\u017easu. Po dobu jedn\u00e9ho t\u00fd\u017ed\u0148a sme zis\u0165ovali, \u010do presne generuje t\u00fato z\u00e1\u0165a\u017e. Uk\u00e1zalo sa, \u017ee ide o tie ist\u00e9 po\u017eiadavky, ktor\u00e9 s\u00fa pren\u00e1\u0161an\u00e9 na na\u0161e API z frontov klientov. V\u0161etko to vygenerovalo asi 50 klientov. Tu sme si uvedomili jednu z na\u0161ich ch\u00fdb \u2013 \u00fapln\u00fa absenciu limitov. <\/p>\n

    Nakoniec sme zaviedli limit na po\u010det s\u00fa\u010dasn\u00fdch po\u017eiadaviek. Z jedn\u00e9ho \u00fa\u010dtu je mo\u017en\u00e9 s\u00fa\u010dasne otvori\u0165 maxim\u00e1lne dva po\u017eiadavky. To je dostato\u010dn\u00e9 na pr\u00e1cu v replik\u00e1cii pre v\u00fdmenu \u00fadajov v d\u00e1vkovom re\u017eime. A t\u00ed, ktor\u00ed chceli pou\u017e\u00edva\u0165 n\u00e1s ako backend, museli od toho momentu viac zodpoveda\u0165 tarifik\u00e1cii, preto\u017ee sme zaviedli vo svojich programov\u00fdch prostriedkoch pr\u00e1cu s viacer\u00fdmi \u00fa\u010dtami.<\/p>\n

    Zarovn\u00e1vame veci do poriadku<\/h2>\n

    \nU\u017e od roku 2014 sa dopyt po existuj\u00facom API stal d\u00f4le\u017eitou s\u00fa\u010das\u0165ou podnikania, pri\u010dom samotn\u00fd API generoval najv\u00e4\u010d\u0161\u00ed objem \u00fadajov pri v\u00fdmene \u00fadajov s klientmi. V roku 2015 sme spustili projekt na zarovnanie API do poriadku. Vybrali sme form\u00e1t JSON namiesto XML a za\u010dali sme ho budova\u0165 na z\u00e1klade charakterist\u00edk, ktor\u00e9 sme zistili pri realiz\u00e1cii predch\u00e1dzaj\u00facej verzie:<\/p>\n

      \n
    1. Mo\u017enos\u0165 spravova\u0165 verzie. Verzionovanie umo\u017e\u0148uje vyvin\u00fa\u0165 nov\u00fa verziu bez zasahovania do existuj\u00facej aplik\u00e1cie a bez naru\u0161ovania pr\u00e1ce pou\u017e\u00edvate\u013eov. <\/li>\n
    2. Mo\u017enos\u0165 pre pou\u017e\u00edvate\u013ea vidie\u0165 metadata priamo v odpovedi, ktor\u00fa dost\u00e1va.<\/li>\n
    3. Mo\u017enos\u0165 v\u00fdmeny ve\u013ek\u00fdch dokumentov. Ak spracov\u00e1vame dokument s po\u010dtom polo\u017eiek viac ako 4-5 tis\u00edc, st\u00e1va sa to probl\u00e9mom pre server: dlh\u00e1 transakcia, dlh\u00fd http-\u017eiados\u0165. Vybudovali sme \u0161peci\u00e1lny mechanizmus, ktor\u00fd umo\u017e\u0148uje aktualizova\u0165 dokument po \u010dastiach a spravova\u0165 jednotliv\u00e9 polo\u017eky tohto dokumentu, ich odosielan\u00edm na server.<\/li>\n
    4. N\u00e1stroje na replik\u00e1ciu \u2014 boli aj v predch\u00e1dzaj\u00facej verzii.<\/li>\n
    5. Limity pre za\u0165a\u017eenie \u2014 ako dedi\u010dstvo probl\u00e9mov, na ktor\u00e9 sme narazili v predch\u00e1dzaj\u00facej verzii. Zaviedli sme limity na po\u010det po\u017eiadaviek v ur\u010ditom \u010dasovom intervale, po\u010det paraleln\u00fdch po\u017eiadaviek a po\u017eiadaviek z jednej ip-adresy.<\/li>\n<\/ol>\n

      \nOd tej doby sme vydali dve men\u0161ie verzie API a spustili nieko\u013eko \u0161pecializovan\u00fdch API, ale celkovo pr\u00edstup ostal bez zmien. Aktualizovan\u00fd form\u00e1t v\u00fdmeny a nov\u00e1 architekt\u00fara umo\u017enili r\u00fdchlej\u0161ie opravovanie nedostatkov v API.<\/p>\n

      API MojeSkladu dnes<\/h2>\n

      \nDnes API MojeSkladu rie\u0161i mno\u017estvo \u00faloh:<\/p>\n