{"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 - reastasime XML (kaks)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

MinuS\u00fcsteemi esimene API ilmus 10 aastat tagasi. Kogu selle aja oleme t\u00f6\u00f6tanud olemasolevate API versioonide kallal ning arendame uusi. Ja m\u00f5ned API versioonid on juba suutnud l\u00f5petada oma elu. <\/p>\n

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

Miks luua teenuse jaoks API<\/h2>\n

\nMeie kliendid, keda on k\u00fcmneid tuhandeid ettev\u00f5tjaid, kasutavad aktiivselt pilvelahendusi: pankade teenuseid, veebipoode, kaupade arvestust, CRM-i. Kui oled \u00fchega liitunud \u2014 on raske peatuda. Ja juba viies, kaheksas, k\u00fcmnes teenus muudab ettev\u00f5tjate t\u00f6\u00f6 lihtsamaks, kuid andmeid nende pilveteenuste vahel kannavad kasutajad k\u00e4sitsi. T\u00f6\u00f6 muutub \u00f5udusunen\u00e4oks.<\/p>\n

Ilmselt on parim lahendus anda kasutajatele v\u00f5imalus andmeid voogesitada erinevate pilveteenuste vahel. N\u00e4iteks importida ja eksportida andmeid failidena, mida saab seej\u00e4rel vajalikku teenusesse laadida. Failid kohandatakse tavaliselt iga teenuse formaadi j\u00e4rgi. See on enam-v\u00e4hem lihtne k\u00e4sit\u00f6\u00f6, kuid teenuste arvu suurenedes muutub selle teostamine \u00fcha keerulisemaks.<\/p>\n

Seet\u00f5ttu on j\u00e4rgmine samm API. Sellega saavuta pilveteenus kasu, sidudes mitu teenust \u00fchte punkti. Sellise \u00f6kos\u00fcsteemi tekkimine t\u00f5mbab uusi kliente, pakkudes lisav\u00f5imalusi. Uue funktsionaalsusega toode muutub kasumlikumaks ja kasulikumaks.<\/p>\n

Kui luua oma tarkvaraliideseid, meelitab see v\u00e4lim\u00fc\u00fcjaid huvitavateks programmeerijateks, kes tunnevad teie toodet API abil. Nad hakkavad looma lahendusi pakkuda API baasil ja teenivad raha oma klientide \u00fclesannete automatiseerimisega.<\/p>\n

MinuLaadi arvestuss\u00fcsteem p\u00f5hineb lihtsates protsessides. Peamine on t\u00f6\u00f6tada esmase dokumentatsiooniga, v\u00f5imalus kaupade vastuv\u00f5tmiseks ja v\u00e4ljastamiseks, samuti saada esmaseid andmeid \u00e4riaruannete koostamiseks. Samuti toetame andmete edastamist, n\u00e4iteks pilvep\u00f5hisesse raamatupidamisse, ja andmete saamist pangas\u00fcsteemidelt v\u00f5i jaem\u00fc\u00fcgipunktidelt. Veelgi enam, me teeme koost\u00f6\u00f6d veebipoed: saame teavet toodete kohta ja edastame andmeid varude kohta.<\/p>\n

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

MinuLaadi esimene API<\/h2>\n

\nMinuLaadi API 10 aasta jooksul oleme meie saanud mitmesuguseid integraatioone, mis v\u00f5imaldavad andmeid vahetada, t\u00f6\u00f6tada pankadega, teha makseid ja kasutada v\u00e4list telefoni.<\/p>\n

Esimesel aastal andsime kasutajatele v\u00f5imaluse eksportida k\u00f5ik andmed XML-formaadis. Sel ajal oli kasutajatele palju arusaadavam ja mugavam hoida andmeid offline, mitte mingis pilves, ja me andsime neile just selle v\u00f5imaluse. Ekspordi k\u00e4ivitamine toimus kasutajaliidese kaudu k\u00e4sitsi eksportimise kaudu. Seega ei saanud API-d veel nii nimetada. <\/p>\n

Siis alustasime koost\u00f6\u00f6d Rusagroga \u2013 nad kasutasid juba \u2018t\u00e4iskasvanud\u2019 ERP-d tootmise ja m\u00fc\u00fcgi planeerimiseks, samas kui vagunite laadimist tehasetes automatiseeriti Moeskladis. Nii said meil alguse esimesed t\u00f5elise API jooned: vahetus meie teenuse ja ERP vahel toimus suurte andmefailide saatmise teel, mis sisaldasid k\u00f5iki dokumendit\u00fc\u00fcpe. <\/p>\n

See on \u00fcsna hea variant andmete paketivahetuseks, kuid koos dokumentidega tuli edastada ka nende s\u00f5ltuvused: teave kaupade, partnerite ja ladude kohta. Sellist segadust on lihtne genereerida eksportimisel, kuid \u00fcsna keeruline importimisel lahti harutada, kuna \u00fches paketis tuleb kogu teave: nii uute dokumentide kui ka juba olemasolevate kohta.<\/p>\n

Esimene XML API ei kestnud kauaks \u2013 kahe aasta p\u00e4rast alustasime selle \u00fcmberkujundamist. Juba selle t\u00f6\u00f6 alguses tegime m\u00f5ned vead liidese ehitamisel.<\/p>\n

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

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

    \n
  1. JAXB m\u00e4rgendus tehti otse entity beans'itele. Andmebaasiga suhtlemiseks kasutame Hibernate'i, ning need samad bean'id said JAXB m\u00e4rgenduse. See viga ilmus peaaegu kohe: iga andmestruktuuri uuendus n\u00f5udis kiiret teavitamist k\u00f5igilt, kes kasutavad API-d, v\u00f5i tuli luua ajutisi lahendusi, mis tagaksid \u00fchilduvuse vana andmestruktuuriga.<\/li>\n
  2. API areneb sammuks, mille me algselt ei m\u00e4\u00e4ratlenud, kui suur osa tootest see on. Me ei m\u00f5elnud ka sellele, kas API on midagi olulist ja kas varasematele klientidele tagasip\u00f6\u00f6rdumisena t\u00e4htsust tuleks toetada. Teatud hetkel oli API kasutajaid umbes 5% kogu v\u00e4ikesest kasutajaskonnast ja neid ignoreeriti. Aja jooksul loodud universaalne filtreerimine viis selleni, et meid hakati kasutama tagaplaanina. See filtreerimine ei olnud sugugi GraphQL, vaid midagi sarnast \u2014 see t\u00f6\u00f6tas lugematute p\u00e4ringuparametrite kaudu. Sellise v\u00f5imsa t\u00f6\u00f6riista t\u00f5ttu oli kasutajatel raske loobuda ning meie suunas suunati p\u00e4ringud niiv\u00f5rd, et need saadeti otse nende e-poe kasutajaliidestest. See olukord osutus ebameeldivaks \u00fcllatuseks, kuna sellise teenuse pakkumine n\u00f5uab teistsugust hinnakujundust ja teistsugust arusaama API-st kui tootest.<\/li>\n
  3. Kuna API arenes mitte p\u00f5hitoote, vaid k\u00f5rvaltoodetena, siis API dokumentatsioon loodi ja avaldati peamiselt tagasitehnoloogia kaudu. See l\u00e4henemine v\u00f5ib tunduda lihtne ja mugav, kuid see on vastuolus lepingulise t\u00f6\u00f6ga. Ehk on mingisugune komponent, millel on eelnevalt m\u00e4\u00e4ratud toimimisviis. Arendaja rakendab selle vastavalt sellele skeemile ja \u00fclesandele, komponent l\u00e4heb testimisele, klient saab toote, mis vastab anal\u00fc\u00fctiku kavatsusele. Tagasitehnoloogia seevastu turule toodab lihtsalt olemasoleva toote: toote, mis sisaldab ajutisi lahendusi, kummalisi otsuseid ja jalgrattaid vajaliku funktsionaalsuse asemel. <\/li>\n
  4. Kogu API kaudu saadud p\u00e4ringute voogu sai anal\u00fc\u00fcsida vaid Nginx'i v\u00f5i rakendusserveri logide kaupa. See ei v\u00f5imaldanud teemasid eristada, v\u00e4lja arvatud kasutajate ja tellijate l\u00f5ikes jagades. Kui rakenduse v\u00f5i klientide registri reguleerimiseks v\u00f5imalusi pole, muutub olukorra anal\u00fc\u00fcsimine v\u00f5imatuks. See probleem m\u00f5jutas API arengut minimaalset, pigem on see seotud selle n\u00f5udlikkuse ja funktsionaalsuse arusaamisega.<\/li>\n<\/ol>\n

    <\/p>\n

    Teine katse: REST API<\/h2>\n

    \n2010. aastal proovime ehitada s\u00fcsteemi, et vahetada online-raamatupidamisega \u2014 Buhsoftiga. See ei \u00f5nnestunud. Kuid integreerimise k\u00e4igus tekkis t\u00e4ie\u00f5iguslik API: REST-teenuse vahetus, kus puudusid vabadused, nagu RPC-k\u00f5nede vormistamine operatsioonide juurde. Koost\u00f6\u00f6 API-ga viidi standardseks REST-re\u017eiimiks: p\u00e4ringureas on olemas \u00fcksuse nimi, ja operatsioon, mida sellel teostatakse, m\u00e4\u00e4ratakse HTTP-meetodi abil. Lisame filtreerimise vastavalt \u00fcksuste uuendusmomendile, ja kasutajatele avanes v\u00f5imalus ehitada replikatsioon oma s\u00fcsteemidega.<\/p>\n

    Samas aastal ilmus API lao- ja kaubaj\u00e4\u00e4kide eksportimiseks. Kasutajatele avanesid l\u00e4bi API s\u00fcsteemi k\u00f5ige v\u00e4\u00e4rtuslikumad osad \u2014 esmaste dokumentide vahetamine ja arvestusandmed kaubaj\u00e4\u00e4kide ja toodete iseloomu kohta.<\/p>\n

    2015. aasta detsembris avaldas RetailCRM meie API-le esimese kolmandate osapoolte teegi. Seda hakati \u00fcsna aktiivselt kasutama ning teenuse populaarsus kasvas \u00fcldiselt kiiremini kui koormus veebiliidesele. \u00dchel hetkest kasvas koormus h\u00fcppeliselt. <\/p>\n

    \"Kirjutasime
    \n
    \n\"Kirjutasime
    \n
    \nJa see h\u00fcpe, millele vasakul nool osutab, j\u00e4ttis meie API teenindava serveri t\u00e4ielikku h\u00e4mmeldusse. Meie tegelesime n\u00e4dal aega selle koormuse p\u00f5hjuse v\u00e4ljaselgitamisega. Selgus, et need olid just need p\u00e4ringud, mis saadeti meie API-le klientide frontidest. K\u00f5ik selle koormuse tekitavad umbes 50 klienti. Siinkohal m\u00f5istsime \u00fche oma vea \u2014 t\u00e4ieliku piirangute puudumise. <\/p>\n

    Seel\u00e4bi paigaldasime piirangud samaaegsete p\u00e4ringute arvule. \u00dche konto alt on n\u00fc\u00fcd lubatud avada korraga mitte rohkem kui kaks p\u00e4ringut. See on piisav replikatsioonire\u017eiimis t\u00f6\u00f6tamiseks andmevahetuses partiire\u017eiimis. Need, kes soovisid meid kasutada tagaplaanina, pidid n\u00fc\u00fcd rohkem arvestama hindadega, kuna nende tarkvaras tuli sisse v\u00f5tta mitme konto haldus.<\/p>\n

    Korra seadmine<\/h2>\n

    \nAlates 2014. aastast on olemasoleva API n\u00f5udmine saanud olulise osa meie tegevusest ning see API genereeris andmevahetuses klientidega suurima andmemahtu. 2015. aastal k\u00e4ivitasime projekti API korrastamiseks. Valisime vorminguks JSON, mitte XML, ja alustasime selle koostamist varasema versiooni rakendamisel tuvastatud omaduste p\u00f5hjal:<\/p>\n

      \n
    1. Versioonihalduse v\u00f5imalus. Versioonimine v\u00f5imaldab arendada uut versiooni, m\u00f5jutamata olemasolevat rakendust ega rikkudes kasutajate t\u00f6\u00f6d. <\/li>\n
    2. Kasutaja v\u00f5imalus n\u00e4ha metaandmeid otse vastuses, mille ta saab.<\/li>\n
    3. Suured dokumentide vahetamise v\u00f5imalused. Kui t\u00f6\u00f6tleme dokumente, millel on rohkem kui 4-5 tuhat \u00fcksust, tekib serverile probleem: pikk tehing, pikk HTTP-p\u00e4ring. Oleme loonud spetsiaalse mehhanismi, mis v\u00f5imaldab dokumenti osade kaupa uuendada ja hallata selle dokumenti \u00fcksikute positsioonide saatmist serverisse.<\/li>\n
    4. Replikatsiooni t\u00f6\u00f6riistad \u2014 need olid ka eelnevas versioonis.<\/li>\n
    5. Kohandamise piirangud \u2014 nagu eelnevas versioonis meid \u00fcllatanud takistused. Oleme kehtestanud piirangud p\u00e4ringute arvu kohta aja jooksul, samaaegsete p\u00e4ringute arvu ja \u00fche IP-aadressi p\u00e4ringute kohta.<\/li>\n<\/ol>\n

      \nSellest ajast oleme v\u00e4lja lasknud kaks v\u00e4ikest API versiooni ja lansseerinud mitu spetsialiseeritud API-d, kuid \u00fcldine l\u00e4henemine on j\u00e4\u00e4nud muutumatuks. Uuendatud vahetusformaadid ja uus arhitektuur on v\u00f5imaldanud API vigu kiiremini parandada.<\/p>\n

      T\u00e4na on MojeSklad API<\/h2>\n

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