{"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\/ro\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Am scris API \u2014 am rupt XML (dou\u0103)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Primul API al MeuStoc a ap\u0103rut acum 10 ani. \u00cen tot acest timp, am lucrat la versiunile existente ale API-ului \u0219i dezvolt\u0103m altele noi. Iar c\u00e2teva versiuni ale API-ului au fost deja \u201e\u00eengropate\u201d. <\/p>\n

\u00cen acest articol vor fi multe informa\u021bii: cum a fost creat API-ul, de ce este necesar pentru serviciile cloud, ce le ofer\u0103 utilizatorilor, pe ce obstacole am dat peste \u0219i ce dorim s\u0103 facem \u00een continuare.
\n<\/a><\/noindex>
\nM\u0103 numesc Oleg Alekseev oalexeev<\/a><\/noindex>, sunt director tehnic \u0219i co-fondator al MeuStoc. <\/p>\n

De ce s\u0103 facem un API pentru serviciu<\/h2>\n

\nClien\u021bii no\u0219tri, care sunt zeci de mii de antreprenori, folosesc activ solu\u021bii cloud: servicii bancare, magazine online, gestiune a stocurilor, CRM. Te conectezi la unul \u2014 \u0219i deja devine greu s\u0103 te opre\u0219ti. Iar acum al cincilea, al optulea, al zecelea serviciu face munca antreprenorilor mai u\u0219oar\u0103, dar utilizatorii transfer\u0103 manual datele \u00eentre aceste servicii cloud. Munca devine un co\u0219mar.<\/p>\n

O solu\u021bie evident\u0103 este s\u0103 oferim utilizatorilor posibilitatea de a transfera date \u00eentre serviciile cloud. De exemplu, s\u0103 importe \u0219i s\u0103 exporte date ca fi\u0219iere, care apoi pot fi \u00eenc\u0103rcate \u00een serviciul dorit. De obicei, fi\u0219ierele sunt adaptate la formatul fiec\u0103rui serviciu. Este o munc\u0103 manual\u0103 mai mult sau mai pu\u021bin simpl\u0103, dar odat\u0103 cu cre\u0219terea num\u0103rului acestor servicii, devine tot mai complicat de realizat.<\/p>\n

Prin urmare, urm\u0103torul pas este API-ul. Cu acesta, serviciul cloud c\u00e2\u0219tig\u0103 prin interconectarea mai multor servicii \u00eentr-un singur punct. Apari\u021bia unei astfel de ecosisteme atrage clien\u021bi noi datorit\u0103 oportunit\u0103\u021bilor suplimentare. Un produs cu o func\u021bionalitate nou\u0103 devine mai avantajos \u0219i util.<\/p>\n

Dac\u0103 se creeaz\u0103 interfe\u021be proprii de programare, acestea atrag v\u00e2nz\u0103tori externi, sub form\u0103 de programatori care cunosc produsul datorit\u0103 API-ului. Ace\u0219tia \u00eencep s\u0103 construiasc\u0103 solu\u021bii bazate pe API-ul propus \u0219i c\u00e2\u0219tig\u0103 bani din automatizarea sarcinilor clien\u021bilor lor.<\/p>\n

Sistemul de contabilitate al MeuStoc se bazeaz\u0103 pe procese simple. Principalul lucru este lucrul cu documentele primare, posibilitatea de a efectua recep\u021bia \u0219i livrarea bunurilor, ob\u021binerea de rapoarte pentru afaceri pe baza documentelor primare. De asemenea, exist\u0103 transferul de date, de exemplu c\u0103tre contabilitatea cloud, \u0219i ob\u021binerea acestora din sistemele bancare sau din punctele de v\u00e2nzare cu am\u0103nuntul. De asemenea, lucr\u0103m cu magazinele online: ob\u021binem informa\u021bii despre produse \u0219i trimitem date despre stocuri.<\/p>\n

\"Am
\n<\/p>\n

Primul API al MeuStoc<\/h2>\n

\n\u00cen cei 10 ani de activitate a MeuStoc cu API, am acumulat diverse integra\u021bii care permit schimbul de date, lucrul cu b\u0103ncile, efectuarea de pl\u0103\u021bi \u0219i utilizarea telefoniei externe.<\/p>\n

\u00cen primul an, am creat posibilitatea de a exporta orice date \u00een format XML. Atunci, utilizatorilor le era mult mai clar \u0219i mai familiar s\u0103 p\u0103streze datele offline, nu \u00een vreun cloud, \u0219i le-am oferit acest lucru. Exportul era ini\u021biat printr-un export manual din interfa\u021b\u0103. A\u0219adar, acest API nu putea fi numit \u00eenc\u0103. <\/p>\n

Atunci am \u00eenceput colaborarea cu compania Rusagro \u2014 ei foloseau deja un ERP \u201ematur\u201d pentru planificarea produc\u021biei \u0219i v\u00e2nz\u0103rilor, iar \u00eenc\u0103rcarea vagoanelor la fabrici era automatizat\u0103 \u00een MeuStoc. A\u0219a au ap\u0103rut primele \u00eenceputuri ale unui API adev\u0103rat: schimbul \u00eentre serviciul nostru \u0219i ERP se realiza prin trimiterea unui fi\u0219ier mare cu date despre toate tipurile de documente. <\/p>\n

Aceasta era o op\u021biune bun\u0103 pentru schimbul de date \u00een vrac, dar \u00eempreun\u0103 cu documentele trebuia s\u0103 transmitem \u0219i dependen\u021bele acestora: informa\u021bii despre produse, parteneri \u0219i depozite. O astfel de amestec\u0103tur\u0103 nu este greu de generat la export, dar este destul de greu de descompus la import, deoarece \u00een acela\u0219i pachet ajung toate informa\u021biile: at\u00e2t despre documentele noi, c\u00e2t \u0219i despre cele existente.<\/p>\n

Primul XML API nu a durat mult \u2014 dup\u0103 doi ani am \u00eenceput restructurarea lui. Chiar de la \u00eenceputul activit\u0103\u021bii sale, am f\u0103cut c\u00e2teva gre\u0219eli \u00een construirea interfe\u021bei de programare.<\/p>\n

\"Am
\nCum a fost realizat XML API: ilustra\u021bie de la unul dintre arhitec\u021bii no\u0219tri. Apropo, a\u0219tepta\u021bi articolele lui.<\/i><\/p>\n

Iat\u0103 gre\u0219elile noastre principale:<\/p>\n

    \n
  1. Markup-ul JAXB a fost realizat direct pe entity beans. Pentru comunicarea cu baza de date, folosim Hibernate, iar pe acelea\u0219i bean-uri a fost realizat markup-ul JAXB. Aceast\u0103 gre\u0219eal\u0103 a ap\u0103rut aproape imediat: orice actualizare a structurii de date ducea la necesitatea de a anun\u021ba urgent pe to\u021bi cei care folosesc API-ul, fie prin construirea de solu\u021bii temporare care s\u0103 asigure compatibilitatea cu structura de date anterioar\u0103.<\/li>\n
  2. API a evoluat ca un fel de supliment, \u0219i ini\u021bial nu am definit ce parte a produsului reprezint\u0103. Nu ne-am g\u00e2ndit nici m\u0103car dac\u0103 API-ul este ceva important, dac\u0103 trebuie s\u0103 men\u021binem compatibilitatea \u00eenapoi pentru primii s\u0103i clien\u021bi. La un moment dat, num\u0103rul utilizatorilor API-ului era de aproximativ 5% din num\u0103rul total, \u0219i nu am acordat aten\u021bie acestora. Filtrarea universal\u0103 realizat\u0103 la vremea respectiv\u0103 a dus la faptul c\u0103 am devenit utiliza\u021bi ca backend. Aceast\u0103 filtrare nu era deloc GraphQL, dar era ceva similar \u2014 func\u021biona printr-o mul\u021bime de parametri \u00eenchisi \u00een interogarea de solicitare. Cu un instrument at\u00e2t de puternic, utilizatorilor le-a fost greu s\u0103 se ab\u021bin\u0103, \u0219i ne-au redirec\u021bionat solicit\u0103rile astfel \u00eenc\u00e2t acestea s\u0103 fie trimise direct de la UI-urile magazinelor lor online. Situa\u021bia a fost o surpriz\u0103 nepl\u0103cut\u0103, deoarece oferirea unui astfel de serviciu ar trebui s\u0103 necesite o tarifare diferit\u0103 \u0219i o \u00een\u021belegere complet diferit\u0103 a API-ului ca produs.<\/li>\n
  3. Din cauza faptului c\u0103 API-ul s-a dezvoltat nu ca un produs principal, documenta\u021bia API-ului a fost realizat\u0103 \u0219i publicat\u0103 ca o m\u0103sur\u0103 de urgen\u021b\u0103 \u2014 prin inginerie invers\u0103. Aceast\u0103 abordare pare a fi destul de simpl\u0103 \u0219i convenabil\u0103, dar contravine contractului de munc\u0103. Aceasta este c\u00e2nd exist\u0103 un anumit component cu o schem\u0103 de func\u021bionare prestabilit\u0103. Dezvoltatorul \u00eel implementeaz\u0103 conform acestei scheme \u0219i sarcinii, componentul este testat, clientul prime\u0219te un produs care corespunde viziunii analistului. Ingineria invers\u0103, pe de alt\u0103 parte, ofer\u0103 pia\u021bei un produs care pur \u0219i simplu exist\u0103: cu solu\u021bii improvizate, decizii ciudate \u0219i \u201ebiciclete\u201d \u00een loc de func\u021bionalitatea dorit\u0103. <\/li>\n
  4. \u00centreaga flux de solicit\u0103ri care venea prin API putea fi analizat nu mai mult dec\u00e2t un log de Nginx sau un server de aplica\u021bii. Aceasta nu permitea s\u0103 fie identificate domeniile tematice, dec\u00e2t s\u0103 fie \u00eemp\u0103r\u021bit pe utilizatori \u0219i abona\u021bi. Dac\u0103 nu exist\u0103 posibilitatea de a regla \u00eenregistrarea aplica\u021biei sau a clien\u021bilor, analiza situa\u021biei devine imposibil\u0103. Aceast\u0103 problem\u0103 a afectat \u00een mic\u0103 m\u0103sur\u0103 dezvoltarea API-ului, mai mult fiind vorba despre \u00een\u021belegerea cererii sale \u0219i a func\u021bionalit\u0103\u021bii sale.<\/li>\n<\/ol>\n

    <\/p>\n

    \u00cencercarea num\u0103rul dou\u0103: REST API<\/h2>\n

    \n\u00cen 2010, am \u00eencercat s\u0103 construim un sistem de schimb cu un serviciu de contabilitate online \u2014 BuxSoft. Nu a func\u021bionat. Totu\u0219i, \u00een procesul de integrare a ap\u0103rut un API complet func\u021bional: un serviciu REST de schimb, unde nu existau derapaje precum apelurile RPC pentru opera\u021biuni. Toat\u0103 comunicarea cu API-ul a fost redus\u0103 la un mod standard pentru REST: \u00een stringul de cerere se con\u021bine denumirea entit\u0103\u021bii, iar opera\u021biunea care se efectueaz\u0103 cu ea este specificat\u0103 prin metoda http. Am ad\u0103ugat filtrare \u00een func\u021bie de momentul actualiz\u0103rii entit\u0103\u021bilor, iar utilizatorii au avut posibilitatea de a construi replic\u0103ri cu sistemele lor.<\/p>\n

    \u00cen acela\u0219i an, a ap\u0103rut un API pentru exportul stocurilor \u0219i a bunurilor disponibile. Utilizatorii au avut acces prin API la cele mai valoroase p\u0103r\u021bi ale sistemului \u2014 schimbul de documente primare \u0219i datele de calcul referitoare la stocuri \u0219i costurile bunurilor.<\/p>\n

    \u00cen decembrie 2015, RetailCRM a publicat prima bibliotec\u0103 extern\u0103 pentru accesarea API-ului nostru. A fost utilizat\u0103 destul de activ, iar \u00een acela\u0219i timp, popularitatea serviciului \u00een general a crescut, iar \u00eenc\u0103rcarea pe API a crescut mai repede dec\u00e2t pe interfa\u021ba web. Odat\u0103, cre\u0219terea s-a transformat \u00eentr-un salt al \u00eenc\u0103rc\u0103rii. <\/p>\n

    \"Am
    \n
    \n\"Am
    \n
    \n\u0218i acest salt, la care se refer\u0103 s\u0103geata din st\u00e2nga, a dus la o mare uimire a serverului care deservesc API-ul nostru. O s\u0103pt\u0103m\u00e2n\u0103 am \u00eencercat s\u0103 \u00een\u021belegem ce anume genereaz\u0103 aceast\u0103 \u00eenc\u0103rcare. S-a dovedit c\u0103 acestea erau exact acele cereri transmise c\u0103tre API-ul nostru de front-end-urile clien\u021bilor. Aproximativ 50 de clien\u021bi au consumat totul. Atunci am realizat una dintre gre\u0219elile noastre \u2014 absen\u021ba total\u0103 a limitelor. <\/p>\n

    \u00cen cele din urm\u0103, am introdus o limit\u0103 pentru num\u0103rul de cereri simultane. De pe un singur cont, acum putea fi deschise simultan nu mai mult de dou\u0103 cereri. Acest lucru este suficient pentru a func\u021biona \u00een modul de replicare pentru schimbul de date \u00een mod de lot. Iar cei care doreau s\u0103 ne utilizeze ca backend au fost nevoi\u021bi s\u0103 se conformeze mai mult tarifelor, deoarece au introdus \u00een instrumentele lor software lucrul cu mai multe conturi.<\/p>\n

    Punt\u0103m lucrurile \u00een ordine<\/h2>\n

    \n\u00cencep\u00e2nd din 2014, cererea pentru API-ul existent a devenit o parte important\u0103 a afacerii, iar API-ul genera cel mai mare volum de date \u00een schimbul de informa\u021bii cu clien\u021bii. \u00cen 2015, am lansat un proiect pentru aducerea API-ului \u00een ordine. Am ales formatul JSON \u00een loc de XML \u0219i am \u00eenceput s\u0103 \u00eel construim pe baza caracteristicilor pe care le-am identificat \u00een implementarea versiunii anterioare:<\/p>\n

      \n
    1. Posibilitatea de a gestiona versiunile. Versiunea permite dezvoltarea unei noi versiuni, f\u0103r\u0103 a afecta aplica\u021bia existent\u0103 \u0219i f\u0103r\u0103 a perturba utilizatorii. <\/li>\n
    2. Posibilitatea utilizatorului de a vedea metadatele \u00een r\u0103spunsul pe care \u00eel prime\u0219te.<\/li>\n
    3. Posibilitatea de a schimba documente mari. Dac\u0103 proces\u0103m un document cu un num\u0103r de articole mai mare de 4-5 mii, acesta devine o problem\u0103 pentru server: tranzac\u021bie lung\u0103, cerere http lung\u0103. Am construit un mecanism special care permite actualizarea documentului pe p\u0103r\u021bi \u0219i gestionarea articolelor individuale din acest document, trimi\u021b\u00e2ndu-le pe server.<\/li>\n
    4. Instrumente pentru replicare \u2014 au existat \u0219i \u00een versiunea anterioar\u0103.<\/li>\n
    5. Limite de \u00eenc\u0103rcare \u2014 ca un mo\u0219tenitor al capcanelor \u00een care am c\u0103lcat \u00een versiunea anterioar\u0103. Am introdus limite pentru num\u0103rul de cereri \u00eentr-un interval de timp, num\u0103rul de cereri paralele \u0219i cererile de la o adres\u0103 IP.<\/li>\n<\/ol>\n

      \nDe atunci, am lansat dou\u0103 versiuni minore ale API-ului \u0219i am ini\u021biat mai multe API-uri specializate, dar, \u00een general, abordarea a r\u0103mas neschimbat\u0103. Formatul actualizat de schimb \u0219i noua arhitectur\u0103 au permis corectarea deficien\u021belor din API mult mai repede.<\/p>\n

      API-ul MeuStoc ast\u0103zi<\/h2>\n

      \nAst\u0103zi, API-ul MeuStoc rezolv\u0103 multe probleme:<\/p>\n