{"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\/et\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Kirjutasime API \u2014 rebenesime XML (kaks)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

MinuSkaapi Esimene API ilmus 10 aastat tagasi. Kogu selle aja oleme t\u00f6\u00f6tanud olemasolevate API versioonide kallal ja arendanud uusi. Ja mitmed API versioonid on juba suutnud maetud. <\/p>\n

Selles artiklis on palju erinevaid teemasid: kuidas API loodi, miks see on vajalik pilveteenusele, mida see kasutajatele annab, milliseid takistusi oleme kohanud ja mida soovime tulevikus teha.
\n<\/a><\/noindex>
\nMinu nimi on Oleg Aleksejev oalexeev<\/a><\/noindex>, olen tehniline direktor ja MeieSkaapi kaasasutaja. <\/p>\n

Miks luua API teenusele<\/h2>\n

\nMeie kliendid, kelleks on k\u00fcmned tuhanded ettev\u00f5tjad, kasutavad aktiivselt pilvelahendusi: pangandust, internetipoode, kaubanduse arvestust, CRM. Kui oled \u00fchendanud \u00fche \u2014 on juba raske peatuda. Ja n\u00fc\u00fcd teeb juba viies, kaheksas, k\u00fcmnes teenus ettev\u00f5tja t\u00f6\u00f6 lihtsamaks, kuid andmeid nende pilveteenuste vahel peavad kasutajad k\u00e4sitsi edastama. T\u00f6\u00f6 muutub \u00f5udusunen\u00e4oks.<\/p>\n

Ilmselge lahendus on anda kasutajatele v\u00f5imalus edastada andmeid pilveteenuste vahel. N\u00e4iteks importida ja eksportida andmeid failidena, mille saab seej\u00e4rel vajalikku teenusesse \u00fcles laadida. Failide tavaliselt muudetakse iga teenuse formaadi j\u00e4rgi. See on enam-v\u00e4hem lihtne k\u00e4sitsit\u00f6\u00f6, kuid teenuste arvu kasvades muutub selle tegemine j\u00e4rjest keerulisemaks.<\/p>\n

Seet\u00f5ttu on j\u00e4rgmine samm \u2014 API. Sellega v\u00f5idab pilveteenus sellest, et \u00fchendab mitmeid teenuseid \u00fches punktis. Sellise \u00f6kos\u00fcsteemi tekkimine t\u00f5mbab uusi kliente t\u00e4nu t\u00e4iendavatele v\u00f5imalustele. Toode koos uue funktsionaalsusega muutub kasulikuks ja atraktiivsemaks.<\/p>\n

Kui luua omaenda programmiliideseid, siis meelitab see m\u00f5ningaid m\u00fc\u00fcgiinimesi, nagu programmeerijad, kes tunnevad teie toodet API kaudu. Nad hakkavad ehitama lahendusi pakkuda saadud API p\u00f5hjal ja teenivad raha oma klientide \u00fclesannete automatiseerimisel.<\/p>\n

MeieSkaapi arvestuss\u00fcsteem p\u00f5hineb lihtsatel protsessidel. Peamine on t\u00f6\u00f6tada esmase dokumentatsiooniga, v\u00f5imalus kaupade vastuv\u00f5tmine ja v\u00e4ljastamine, saada \u00e4ri jaoks aruandeid algdokumentide p\u00f5hjal. Samuti on olemas andmete edastamine, n\u00e4iteks pilve raamatupidamisse, ja nende saamine pankade s\u00fcsteemidest v\u00f5i jaepoodidest. Samuti tegeleme internetipoodidega: saame teavet kaupade kohta ja edastame andmeid j\u00e4\u00e4kide kohta.<\/p>\n

\"Kirjutasime
\n<\/p>\n

MinuSLA API<\/h2>\n

\n10 aasta jooksul, mil MinuSLA on API-d kasutanud, oleme arendanud mitmeid integreerimisi, mis v\u00f5imaldavad andmeid vahetada, t\u00f6\u00f6tada pankadega, teostada makseid ja kasutada v\u00e4liseid telefoniteenuseid.<\/p>\n

Esimese aasta jooksul lisasime v\u00f5imaluse eksportida andmeid mis tahes formaadis XML. Toona oli kasutajatel palju lihtsam ja tuttavam hoida andmeid offline, mitte kuskil pilves, ja meie andsime neile selle v\u00f5imaluse. Ekspordiprotsess k\u00e4ivitus k\u00e4sitsi eksportimise kaudu kasutajaliidest. Seega ei saanud me seda veel API-ks nimetada. <\/p>\n

Sel ajal alustasime koost\u00f6\u00f6d Rusagro-ga \u2014 nad kasutasid juba t\u00e4isfunktsionaalset ERP-d tootmise ja m\u00fc\u00fcgi planeerimiseks, kuid vagunite koormamine tehastes automatiseeriti MinuSLA-s. Nii tekkisid meil esimesed t\u00f5elise API alged: andmevahetus meie teenuse ja ERP vahel toimus suurte andmefailide saatmise kaudu, mis sisaldas k\u00f5igi dokumendit\u00fc\u00fcpide andmeid. <\/p>\n

See oli hea lahendus andmete pakkide vahetamiseks, kuid koos dokumentidega tuli edastada ka nende s\u00f5ltuvused: teave kaupade, klientide ja ladude kohta. Sellist kooslust on eksportimisel lihtne genereerida, kuid impordil on seda \u00fcsna keeruline l\u00f5hkuda, kuna \u00fches paketis saabub kogu teave: nii uute dokumentide kui ka juba olemasolevate kohta.<\/p>\n

Esimene XML API ei elanud kaua \u2014 kahe aasta p\u00e4rast hakkasime seda \u00fcmber ehitama. Juba API k\u00e4ivitamise alguses tegime mitmeid vigu programmeerimisliidese loomisel.<\/p>\n

\"Kirjutasime
\nNii loodi XML API: \u00fcks meie arhitektide illustratsioon. Muide, oodake tema artikleid.<\/i><\/p>\n

Siin on meie peamised vead:<\/p>\n

    \n
  1. JAXB m\u00e4rgistus tehti otse entity beans'idele. Andmebaasiga suhtlemiseks kasutame Hibernate'i ja sama m\u00e4rgistus tehti ka nendele b\u0131inidele. See viga ilmnes peaaegu kohe: iga andmestruktuuri v\u00e4rskendus t\u00f5i kaasa vajaduse kiiresti teavitada k\u00f5iki, kes API-d kasutavad, v\u00f5i ehitada ajutisi lahendusi, mis tagaksid \u00fchilduvuse eelmise andmestruktuuriga.<\/li>\n
  2. API kasvas v\u00e4lja kui mingi lisand, ja algselt me ei m\u00e4\u00e4ratlenud, millise osa toote sellest moodustab. Me ei m\u00f5elnud ka sellele, kas API on midagi olulist, kas esimeste klientide jaoks tuleb tagada tagurpidi \u00fchilduvus. Mingil hetkel oli API kasutajate arv umbes 5% kogu v\u00e4ikesest koguarvust, ja neile ei p\u00f6\u00f6rdutud t\u00e4helepanu. Koostatud \u00fcldine filtreerimine viis selleni, et meid hakati kasutama tagaplaanina. See filtreerimine ei olnud t\u00e4pselt GraphQL, vaid midagi sarnast \u2014 t\u00f6\u00f6tas l\u00e4bi tohutu hulga p\u00e4ringuparameterite. Sellise v\u00f5imsa t\u00f6\u00f6riistaga oli kasutajatel raske vastu pidada, ja meie juurde suunati p\u00e4ringud otse nende e-poodide UI-st. Situatsioon osutus ebameeldivaks \u00fcllatuseks, kuna sellise teenuse pakkumine peaks n\u00f5udma teistsugust hinnakujundust ja hoopis teistsugust arusaama API-st kui tootest.<\/li>\n
  3. Kuna API arenes mitte kui peamine toode, siis API dokumentatsiooni koostamine ja avaldamine toimus allesj\u00e4\u00e4vate ressursside kaudu \u2014 p\u00f6\u00f6rdprojekteerimise teel. See l\u00e4henemine n\u00e4ib olevat piisavalt lihtne ja mugav, kuid on vastuolus lepingu alusel t\u00f6\u00f6tamisega. See on siis, kui on mingi komponent eelpandud t\u00f6\u00f6schemas. Arendaja rakendab selle vastavalt sellele schema'le ja \u00fclesandele, komponent l\u00e4bib testimise, klient saab toote, mis vastab anal\u00fc\u00fctiku kavandile. P\u00f6\u00f6rdprojekteerimine aga paiskab turule toote, mis lihtsalt eksisteerib: lahendustega, kummaliste otsustega ja jalgratastega vajaliku funktsionaalsuse asemel. <\/li>\n
  4. Kogu p\u00e4ringute voogu, mis tuli l\u00e4bi API, sai anal\u00fc\u00fcsida mitte rohkem kui Nginx'i v\u00f5i rakendusserveri logina. See ei v\u00f5imaldanud teemaalasid v\u00e4lja selgitada, v\u00e4lja arvatud kasutajate ja tellijate kaupa jagada. Kui pole v\u00f5imalik reguleerida rakenduse v\u00f5i klientide registreerimist, muutub olukorra anal\u00fc\u00fcsimine v\u00f5imatuks. See probleem m\u00f5jutas API arendamist k\u00f5ige v\u00e4hem, see puudutab rohkem arusaamist selle n\u00f5udlusest ja funktsionaalsete v\u00f5imaluste t\u00e4itmisest.<\/li>\n<\/ol>\n

    <\/p>\n

    Katse number kaks: REST API<\/h2>\n

    \n2010. aastal p\u00fc\u00fcdsime luua online-raamatupidamise s\u00fcsteemi, mille nimeks oli BuhSoft. See ei \u00f5nnestunud. K\u00fcll aga tekis integreerimise k\u00e4igus t\u00e4isv\u00e4\u00e4rtuslik API: REST-teenus, kus ei olnud selliseid k\u00f5rvalekaldeid nagu RPC-k\u00f5nede tegemine. Kogu suhtlemine API-ga viidi standardsele REST-re\u017eiimile: p\u00e4ringute viisis on toodud entiteedi nimi ja toiming, mida sellega tehakse, m\u00e4\u00e4ratakse http-meetodi abil. Lisatud said olemasolu uuendamise filtreerimine ning kasutajatele tekkis v\u00f5imalus replikatsiooni ehitada oma s\u00fcsteemidega.<\/p>\n

    Samas aastal ilmus API, mis v\u00f5imaldas laoseisu ja toodete j\u00e4\u00e4ke eksportida. Kasutajatele said API kaudu kergesti k\u00e4tte s\u00fcsteemi k\u00f5ige v\u00e4\u00e4rtuslikumad osad \u2014 esialgsete dokumentide vahetus ja arvutustooted j\u00e4\u00e4kide ja kaupade enda hindade kohta.<\/p>\n

    Detsembris 2015 avaldas RetailCRM esimese kolmanda osapoole teegi meie API-le ligip\u00e4\u00e4suks. Seda hakati \u00fcsna aktiivselt kasutama, samal ajal kasvas ka teenuse populaarsus; koormus API-le suurenes kiiremini kui veebiliidese koormus. \u00dcks kord muutus kasv t\u00f5usuks. <\/p>\n

    \"Kirjutasime
    \n
    \n\"Kirjutasime
    \n
    \nJa see t\u00f5us, millega vasak pool n\u00e4itab noolt, p\u00f5hjustas t\u00e4ielikku \u00fcllatust serveris, mis teenindab meie API-d. N\u00e4dala jooksul uurisime, mis tegelikult seda koormust genereeris. Selgus, et need olid just need p\u00e4ringud, mis saadeti meie API-le klientide frontidest. K\u00f5ike neelas umbes 50 klienti. Siin saime aru \u00fchest meie veast - t\u00e4ielik piirangute puudumine. <\/p>\n

    Kokkuv\u00f5ttes kehtestasime piiri samaaegsete p\u00e4ringute arvule. \u00dchest kontost v\u00f5is korraga avada mitte rohkem kui kaks p\u00e4ringut. See piisab replikatsiooni re\u017eiimis t\u00f6\u00f6tamiseks andmete vahetamisel paketi re\u017eiimis. Need, kes soovisid meid kasutada tagaplaanina, pidid alates sellest hetkest rohkem vastama hindadele, kuna nad l\u00fclitasid oma tarkvaradesse t\u00f6\u00f6 mitme konto kaudu.<\/p>\n

    Viime korda korda<\/h2>\n

    \nJuba 2014. aastast alates on olemasoleva API n\u00f5udlus muutunud osa meie \u00e4ritegevusest, samas genereerib API suurima andmemahtu klientidega andmete vahetamisel. 2015. aastal alustasime projekti API korrastamiseks. Valisime formaadiks JSON, mitte XML ning hakkasime seda ehitama eelnevalt avastatud omaduste p\u00f5hjal:<\/p>\n

      \n
    1. Versioonide haldamise v\u00f5imalus. Versioonimine v\u00f5imaldab v\u00e4lja t\u00f6\u00f6tada uue versiooni, m\u00f5jutamata olemasolevat rakendust ja rikkumata kasutajate t\u00f6\u00f6d. <\/li>\n
    2. Kasutaja v\u00f5imalus n\u00e4ha vastuses metainfot, mida ta saab.<\/li>\n
    3. Suure dokumentide vahetuse v\u00f5imalus. Kui t\u00f6\u00f6tleme dokumenti, kus on rohkem kui 4-5 tuhat positsiooni, saab see serverile probleemiks: pikk tehing, pikk http-p\u00e4ring. Oleme loonud spetsiaalse mehhanismi, mis v\u00f5imaldab dokumenti uuendada osade kaupa ja hallata selle dokumendi eraldiseisvaid positsioone, saates need serverisse.<\/li>\n
    4. Replikatsioonivahendid \u2014 olid ka eelmisest versioonist.<\/li>\n
    5. Koormuse piirangud \u2014 kui j\u00e4\u00e4nus eelmisest versioonist. Sisse viidud piirangud p\u00e4ringute arvu osas ajavahemiku jooksul, samaaegsete p\u00e4ringute arvu ja p\u00e4ringute arvu \u00fche ip-aadressi pealt.<\/li>\n<\/ol>\n

      \nSellest ajast oleme v\u00e4lja lasknud kaks v\u00e4ikest versiooni API-st ja k\u00e4ivitanud mitu spetsialiseeritud API-d, kuid \u00fcldine l\u00e4henemine on j\u00e4\u00e4nud muutumatuks. Uuendatud andmevahetuse formaat ja uus arhitehtuuri v\u00f5imaldasid API n\u00f5rkusi palju kiiremini parandada.<\/p>\n

      MinuLaod API t\u00e4na<\/h2>\n

      \nT\u00e4na lahendab MinuLaod API palju \u00fclesandeid:<\/p>\n