Kirjutasime API — rebenesime XML (kaks)

MinuSkaapi Esimene API ilmus 10 aastat tagasi. Kogu selle aja oleme töötanud olemasolevate API versioonide kallal ja arendanud uusi. Ja mitmed API versioonid on juba suutnud maetud.

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.

Minu nimi on Oleg Aleksejev oalexeev, olen tehniline direktor ja MeieSkaapi kaasasutaja.

Miks luua API teenusele

Meie kliendid, kelleks on kümned tuhanded ettevõtjad, kasutavad aktiivselt pilvelahendusi: pangandust, internetipoode, kaubanduse arvestust, CRM. Kui oled ühendanud ühe — on juba raske peatuda. Ja nüüd teeb juba viies, kaheksas, kümnes teenus ettevõtja töö lihtsamaks, kuid andmeid nende pilveteenuste vahel peavad kasutajad käsitsi edastama. Töö muutub õudusunenäoks.

Ilmselge lahendus on anda kasutajatele võimalus edastada andmeid pilveteenuste vahel. Näiteks importida ja eksportida andmeid failidena, mille saab seejärel vajalikku teenusesse üles laadida. Failide tavaliselt muudetakse iga teenuse formaadi järgi. See on enam-vähem lihtne käsitsitöö, kuid teenuste arvu kasvades muutub selle tegemine järjest keerulisemaks.

Seetõttu on järgmine samm — API. Sellega võidab pilveteenus sellest, et ühendab mitmeid teenuseid ühes punktis. Sellise ökosüsteemi tekkimine tõmbab uusi kliente tänu täiendavatele võimalustele. Toode koos uue funktsionaalsusega muutub kasulikuks ja atraktiivsemaks.

Kui luua omaenda programmiliideseid, siis meelitab see mõningaid müügiinimesi, nagu programmeerijad, kes tunnevad teie toodet API kaudu. Nad hakkavad ehitama lahendusi pakkuda saadud API põhjal ja teenivad raha oma klientide ülesannete automatiseerimisel.

MeieSkaapi arvestussüsteem põhineb lihtsatel protsessidel. Peamine on töötada esmase dokumentatsiooniga, võimalus kaupade vastuvõtmine ja väljastamine, saada äri jaoks aruandeid algdokumentide põhjal. Samuti on olemas andmete edastamine, näiteks pilve raamatupidamisse, ja nende saamine pankade süsteemidest või jaepoodidest. Samuti tegeleme internetipoodidega: saame teavet kaupade kohta ja edastame andmeid jääkide kohta.

MinuSLA API

10 aasta jooksul, mil MinuSLA on API-d kasutanud, oleme arendanud mitmeid integreerimisi, mis võimaldavad andmeid vahetada, töötada pankadega, teostada makseid ja kasutada väliseid telefoniteenuseid.

Esimese aasta jooksul lisasime võimaluse 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õimaluse. Ekspordiprotsess käivitus käsitsi eksportimise kaudu kasutajaliidest. Seega ei saanud me seda veel API-ks nimetada.

Sel ajal alustasime koostööd Rusagro-ga — nad kasutasid juba täisfunktsionaalset ERP-d tootmise ja müügi planeerimiseks, kuid vagunite koormamine tehastes automatiseeriti MinuSLA-s. Nii tekkisid meil esimesed tõelise API alged: andmevahetus meie teenuse ja ERP vahel toimus suurte andmefailide saatmise kaudu, mis sisaldas kõigi dokumenditüüpide andmeid.

See oli hea lahendus andmete pakkide vahetamiseks, kuid koos dokumentidega tuli edastada ka nende sõltuvused: teave kaupade, klientide ja ladude kohta. Sellist kooslust on eksportimisel lihtne genereerida, kuid impordil on seda üsna keeruline lõhkuda, kuna ühes paketis saabub kogu teave: nii uute dokumentide kui ka juba olemasolevate kohta.

Esimene XML API ei elanud kaua — kahe aasta pärast hakkasime seda ümber ehitama. Juba API käivitamise alguses tegime mitmeid vigu programmeerimisliidese loomisel.

Nii loodi XML API: üks meie arhitektide illustratsioon. Muide, oodake tema artikleid.

Siin on meie peamised vead:

1. JAXB märgistus tehti otse entity beans'idele. Andmebaasiga suhtlemiseks kasutame Hibernate'i ja sama märgistus tehti ka nendele bıinidele. See viga ilmnes peaaegu kohe: iga andmestruktuuri värskendus tõi kaasa vajaduse kiiresti teavitada kõiki, kes API-d kasutavad, või ehitada ajutisi lahendusi, mis tagaksid ühilduvuse eelmise andmestruktuuriga.
2. API kasvas välja kui mingi lisand, ja algselt me ei määratlenud, millise osa toote sellest moodustab. Me ei mõelnud ka sellele, kas API on midagi olulist, kas esimeste klientide jaoks tuleb tagada tagurpidi ühilduvus. Mingil hetkel oli API kasutajate arv umbes 5% kogu väikesest koguarvust, ja neile ei pöördutud tähelepanu. Koostatud üldine filtreerimine viis selleni, et meid hakati kasutama tagaplaanina. See filtreerimine ei olnud täpselt GraphQL, vaid midagi sarnast — töötas läbi tohutu hulga päringuparameterite. Sellise võimsa tööriistaga oli kasutajatel raske vastu pidada, ja meie juurde suunati päringud otse nende e-poodide UI-st. Situatsioon osutus ebameeldivaks üllatuseks, kuna sellise teenuse pakkumine peaks nõudma teistsugust hinnakujundust ja hoopis teistsugust arusaama API-st kui tootest.
3. Kuna API arenes mitte kui peamine toode, siis API dokumentatsiooni koostamine ja avaldamine toimus allesjäävate ressursside kaudu — pöördprojekteerimise teel. See lähenemine näib olevat piisavalt lihtne ja mugav, kuid on vastuolus lepingu alusel töötamisega. See on siis, kui on mingi komponent eelpandud tööschemas. Arendaja rakendab selle vastavalt sellele schema'le ja ülesandele, komponent läbib testimise, klient saab toote, mis vastab analüütiku kavandile. Pöördprojekteerimine aga paiskab turule toote, mis lihtsalt eksisteerib: lahendustega, kummaliste otsustega ja jalgratastega vajaliku funktsionaalsuse asemel.
4. Kogu päringute voogu, mis tuli läbi API, sai analüüsida mitte rohkem kui Nginx'i või rakendusserveri logina. See ei võimaldanud teemaalasid välja selgitada, välja arvatud kasutajate ja tellijate kaupa jagada. Kui pole võimalik reguleerida rakenduse või klientide registreerimist, muutub olukorra analüüsimine võimatuks. See probleem mõjutas API arendamist kõige vähem, see puudutab rohkem arusaamist selle nõudlusest ja funktsionaalsete võimaluste täitmisest.

Katse number kaks: REST API

2010. aastal püüdsime luua online-raamatupidamise süsteemi, mille nimeks oli BuhSoft. See ei õnnestunud. Küll aga tekis integreerimise käigus täisväärtuslik API: REST-teenus, kus ei olnud selliseid kõrvalekaldeid nagu RPC-kõnede tegemine. Kogu suhtlemine API-ga viidi standardsele REST-režiimile: päringute viisis on toodud entiteedi nimi ja toiming, mida sellega tehakse, määratakse http-meetodi abil. Lisatud said olemasolu uuendamise filtreerimine ning kasutajatele tekkis võimalus replikatsiooni ehitada oma süsteemidega.

Samas aastal ilmus API, mis võimaldas laoseisu ja toodete jääke eksportida. Kasutajatele said API kaudu kergesti kätte süsteemi kõige väärtuslikumad osad — esialgsete dokumentide vahetus ja arvutustooted jääkide ja kaupade enda hindade kohta.

Detsembris 2015 avaldas RetailCRM esimese kolmanda osapoole teegi meie API-le ligipääsuks. Seda hakati üsna aktiivselt kasutama, samal ajal kasvas ka teenuse populaarsus; koormus API-le suurenes kiiremini kui veebiliidese koormus. Üks kord muutus kasv tõusuks.

Ja see tõus, millega vasak pool näitab noolt, põhjustas täielikku üllatust serveris, mis teenindab meie API-d. Nädala jooksul uurisime, mis tegelikult seda koormust genereeris. Selgus, et need olid just need päringud, mis saadeti meie API-le klientide frontidest. Kõike neelas umbes 50 klienti. Siin saime aru ühest meie veast - täielik piirangute puudumine.

Kokkuvõttes kehtestasime piiri samaaegsete päringute arvule. Ühest kontost võis korraga avada mitte rohkem kui kaks päringut. See piisab replikatsiooni režiimis töötamiseks andmete vahetamisel paketi režiimis. Need, kes soovisid meid kasutada tagaplaanina, pidid alates sellest hetkest rohkem vastama hindadele, kuna nad lülitasid oma tarkvaradesse töö mitme konto kaudu.

Viime korda korda

Juba 2014. aastast alates on olemasoleva API nõudlus muutunud osa meie äritegevusest, 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õhjal:

1. Versioonide haldamise võimalus. Versioonimine võimaldab välja töötada uue versiooni, mõjutamata olemasolevat rakendust ja rikkumata kasutajate tööd.
2. Kasutaja võimalus näha vastuses metainfot, mida ta saab.
3. Suure dokumentide vahetuse võimalus. Kui töötleme dokumenti, kus on rohkem kui 4-5 tuhat positsiooni, saab see serverile probleemiks: pikk tehing, pikk http-päring. Oleme loonud spetsiaalse mehhanismi, mis võimaldab dokumenti uuendada osade kaupa ja hallata selle dokumendi eraldiseisvaid positsioone, saates need serverisse.
4. Replikatsioonivahendid — olid ka eelmisest versioonist.
5. Koormuse piirangud — kui jäänus eelmisest versioonist. Sisse viidud piirangud päringute arvu osas ajavahemiku jooksul, samaaegsete päringute arvu ja päringute arvu ühe ip-aadressi pealt.

Sellest ajast oleme välja lasknud kaks väikest versiooni API-st ja käivitanud mitu spetsialiseeritud API-d, kuid üldine lähenemine on jäänud muutumatuks. Uuendatud andmevahetuse formaat ja uus arhitehtuuri võimaldasid API nõrkusi palju kiiremini parandada.

MinuLaod API täna

Täna lahendab MinuLaod API palju ülesandeid:

• andmete vahetamine veebipoodidega, raamatupidamissüsteemidega, pankadega;
• arvutuste, raportite saamine;
• kasutamine kliendirakenduste tagaplaanina — meie mobiilrakendused ja töölauakassa töötavad API kaudu
• andmete muudatused MinuLaos — webhooks;
• telefoniteenused;
• loyalty-süsteemid.

API põhjal kirjutas meie peadirektor Askar Rahimberdiev rhino nelja tunni jooksul telegrammi-boti, mis tõmbab API kaudu jääke: github.com/arahimberdiev/com-lognex-telegram-moysklad-stock

Nüüd kuivad numbrid.

Siin on meie statistika vanast REST API-st:

• 400 ettevõtet;
• 600 kasutajat;
• 2 miljonit päringut päevas;
• 200 GB/päevas väljaminevat liiklust.

Ja siin on, kuhu me jõudsime kõikide MinuLaod API-dega:

• üle 70 integratsiooni (osa neist on võimalik vaadata siin www.moysklad.ru/integratsii);
• 8500 ettevõtet;
• 12 000 kasutajat;
• 46 miljonit päringut päevas;
• 2 TB/päevas väljaminevat liiklust.

Mis edasi

API arenduskava on aktiivses arutelus. Püüame arvesse võtta kasutajate antud kogemusi. Mitte alati ei õnnestu kõike kohe teha, kuid uus API versioon, mis hõlmab mugavamaid metaandmeid ja vähem keerulist struktuuri, OAuth autentimiseks, ja API rakenduste liidestamiseks, on juba lähedal.

Uudiste jälgimiseks külastage spetsiaalset arendajate lehte, mis on seotud MinuLadu integratsioonidega: dev.muinladu.ee.

Allikas: habr.com