MinuSüsteemi esimene API ilmus 10 aastat tagasi. Kogu selle aja oleme töötanud olemasolevate API versioonide kallal ning arendame uusi. Ja mõned API versioonid on juba suutnud lõpetada oma elu.
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.
Minu nimi on Oleg Alekseev , olen minuSüsteemi tehniline direktor ja kaasasutaja.
Miks luua teenuse jaoks API
Meie kliendid, keda on kümneid tuhandeid ettevõtjaid, kasutavad aktiivselt pilvelahendusi: pankade teenuseid, veebipoode, kaupade arvestust, CRM-i. Kui oled ühega liitunud — on raske peatuda. Ja juba viies, kaheksas, kümnes teenus muudab ettevõtjate töö lihtsamaks, kuid andmeid nende pilveteenuste vahel kannavad kasutajad käsitsi. Töö muutub õudusunenäoks.
Ilmselt on parim lahendus anda kasutajatele võimalus andmeid voogesitada erinevate pilveteenuste vahel. Näiteks importida ja eksportida andmeid failidena, mida saab seejärel vajalikku teenusesse laadida. Failid kohandatakse tavaliselt iga teenuse formaadi järgi. See on enam-vähem lihtne käsitöö, kuid teenuste arvu suurenedes muutub selle teostamine üha keerulisemaks.
Seetõttu on järgmine samm API. Sellega saavuta pilveteenus kasu, sidudes mitu teenust ühte punkti. Sellise ökosüsteemi tekkimine tõmbab uusi kliente, pakkudes lisavõimalusi. Uue funktsionaalsusega toode muutub kasumlikumaks ja kasulikumaks.
Kui luua oma tarkvaraliideseid, meelitab see välimüüjaid huvitavateks programmeerijateks, kes tunnevad teie toodet API abil. Nad hakkavad looma lahendusi pakkuda API baasil ja teenivad raha oma klientide ülesannete automatiseerimisega.
MinuLaadi arvestussüsteem põhineb lihtsates protsessides. Peamine on töötada esmase dokumentatsiooniga, võimalus kaupade vastuvõtmiseks ja väljastamiseks, samuti saada esmaseid andmeid äriaruannete koostamiseks. Samuti toetame andmete edastamist, näiteks pilvepõhisesse raamatupidamisse, ja andmete saamist pangasüsteemidelt või jaemüügipunktidelt. Veelgi enam, me teeme koostööd veebipoed: saame teavet toodete kohta ja edastame andmeid varude kohta.
MinuLaadi esimene API
MinuLaadi API 10 aasta jooksul oleme meie saanud mitmesuguseid integraatioone, mis võimaldavad andmeid vahetada, töötada pankadega, teha makseid ja kasutada välist telefoni.
Esimesel aastal andsime kasutajatele võimaluse eksportida kõik andmed XML-formaadis. Sel ajal oli kasutajatele palju arusaadavam ja mugavam hoida andmeid offline, mitte mingis pilves, ja me andsime neile just selle võimaluse. Ekspordi käivitamine toimus kasutajaliidese kaudu käsitsi eksportimise kaudu. Seega ei saanud API-d veel nii nimetada.
Siis alustasime koostööd Rusagroga – nad kasutasid juba ‘täiskasvanud’ ERP-d tootmise ja müügi planeerimiseks, samas kui vagunite laadimist tehasetes automatiseeriti Moeskladis. Nii said meil alguse esimesed tõelise API jooned: vahetus meie teenuse ja ERP vahel toimus suurte andmefailide saatmise teel, mis sisaldasid kõiki dokumenditüüpe.
See on üsna hea variant andmete paketivahetuseks, kuid koos dokumentidega tuli edastada ka nende sõltuvused: teave kaupade, partnerite ja ladude kohta. Sellist segadust on lihtne genereerida eksportimisel, kuid üsna keeruline importimisel lahti harutada, kuna ühes paketis tuleb kogu teave: nii uute dokumentide kui ka juba olemasolevate kohta.
Esimene XML API ei kestnud kauaks – kahe aasta pärast alustasime selle ümberkujundamist. Juba selle töö alguses tegime mõned vead liidese ehitamisel.
Kuidas XML API loodi: illustratsioon meie arhitektidelt. Muide, oodake tema artikleid.
Siin on meie peamised vead:
- JAXB märgendus tehti otse entity beans'itele. Andmebaasiga suhtlemiseks kasutame Hibernate'i, ning need samad bean'id said JAXB märgenduse. See viga ilmus peaaegu kohe: iga andmestruktuuri uuendus nõudis kiiret teavitamist kõigilt, kes kasutavad API-d, või tuli luua ajutisi lahendusi, mis tagaksid ühilduvuse vana andmestruktuuriga.
- API areneb sammuks, mille me algselt ei määratlenud, kui suur osa tootest see on. Me ei mõelnud ka sellele, kas API on midagi olulist ja kas varasematele klientidele tagasipöördumisena tähtsust tuleks toetada. Teatud hetkel oli API kasutajaid umbes 5% kogu väikesest 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 — see töötas lugematute päringuparametrite kaudu. Sellise võimsa tööriista tõttu oli kasutajatel raske loobuda ning meie suunas suunati päringud niivõrd, et need saadeti otse nende e-poe kasutajaliidestest. See olukord osutus ebameeldivaks üllatuseks, kuna sellise teenuse pakkumine nõuab teistsugust hinnakujundust ja teistsugust arusaama API-st kui tootest.
- Kuna API arenes mitte põhitoote, vaid kõrvaltoodetena, siis API dokumentatsioon loodi ja avaldati peamiselt tagasitehnoloogia kaudu. See lähenemine võib tunduda lihtne ja mugav, kuid see on vastuolus lepingulise tööga. Ehk on mingisugune komponent, millel on eelnevalt määratud toimimisviis. Arendaja rakendab selle vastavalt sellele skeemile ja ülesandele, komponent läheb testimisele, klient saab toote, mis vastab analüütiku kavatsusele. Tagasitehnoloogia seevastu turule toodab lihtsalt olemasoleva toote: toote, mis sisaldab ajutisi lahendusi, kummalisi otsuseid ja jalgrattaid vajaliku funktsionaalsuse asemel.
- Kogu API kaudu saadud päringute voogu sai analüüsida vaid Nginx'i või rakendusserveri logide kaupa. See ei võimaldanud teemasid eristada, välja arvatud kasutajate ja tellijate lõikes jagades. Kui rakenduse või klientide registri reguleerimiseks võimalusi pole, muutub olukorra analüüsimine võimatuks. See probleem mõjutas API arengut minimaalset, pigem on see seotud selle nõudlikkuse ja funktsionaalsuse arusaamisega.
Teine katse: REST API
2010. aastal proovime ehitada süsteemi, et vahetada online-raamatupidamisega — Buhsoftiga. See ei õnnestunud. Kuid integreerimise käigus tekkis täieõiguslik API: REST-teenuse vahetus, kus puudusid vabadused, nagu RPC-kõnede vormistamine operatsioonide juurde. Koostöö API-ga viidi standardseks REST-režiimiks: päringureas on olemas üksuse nimi, ja operatsioon, mida sellel teostatakse, määratakse HTTP-meetodi abil. Lisame filtreerimise vastavalt üksuste uuendusmomendile, ja kasutajatele avanes võimalus ehitada replikatsioon oma süsteemidega.
Samas aastal ilmus API lao- ja kaubajääkide eksportimiseks. Kasutajatele avanesid läbi API süsteemi kõige väärtuslikumad osad — esmaste dokumentide vahetamine ja arvestusandmed kaubajääkide ja toodete iseloomu kohta.
2015. aasta detsembris avaldas RetailCRM meie API-le esimese kolmandate osapoolte teegi. Seda hakati üsna aktiivselt kasutama ning teenuse populaarsus kasvas üldiselt kiiremini kui koormus veebiliidesele. Ühel hetkest kasvas koormus hüppeliselt.
Ja see hüpe, millele vasakul nool osutab, jättis meie API teenindava serveri täielikku hämmeldusse. Meie tegelesime nädal aega selle koormuse põhjuse väljaselgitamisega. Selgus, et need olid just need päringud, mis saadeti meie API-le klientide frontidest. Kõik selle koormuse tekitavad umbes 50 klienti. Siinkohal mõistsime ühe oma vea — täieliku piirangute puudumise.
Seeläbi paigaldasime piirangud samaaegsete päringute arvule. Ühe konto alt on nüüd lubatud avada korraga mitte rohkem kui kaks päringut. See on piisav replikatsioonirežiimis töötamiseks andmevahetuses partiirežiimis. Need, kes soovisid meid kasutada tagaplaanina, pidid nüüd rohkem arvestama hindadega, kuna nende tarkvaras tuli sisse võtta mitme konto haldus.
Korra seadmine
Alates 2014. aastast on olemasoleva API nõudmine saanud olulise osa meie tegevusest ning see API genereeris andmevahetuses klientidega suurima andmemahtu. 2015. aastal käivitasime projekti API korrastamiseks. Valisime vorminguks JSON, mitte XML, ja alustasime selle koostamist varasema versiooni rakendamisel tuvastatud omaduste põhjal:
- Versioonihalduse võimalus. Versioonimine võimaldab arendada uut versiooni, mõjutamata olemasolevat rakendust ega rikkudes kasutajate tööd.
- Kasutaja võimalus näha metaandmeid otse vastuses, mille ta saab.
- Suured dokumentide vahetamise võimalused. Kui töötleme dokumente, millel on rohkem kui 4-5 tuhat üksust, tekib serverile probleem: pikk tehing, pikk HTTP-päring. Oleme loonud spetsiaalse mehhanismi, mis võimaldab dokumenti osade kaupa uuendada ja hallata selle dokumenti üksikute positsioonide saatmist serverisse.
- Replikatsiooni tööriistad — need olid ka eelnevas versioonis.
- Kohandamise piirangud — nagu eelnevas versioonis meid üllatanud takistused. Oleme kehtestanud piirangud päringute arvu kohta aja jooksul, samaaegsete päringute arvu ja ühe IP-aadressi päringute kohta.
Sellest ajast oleme välja lasknud kaks väikest API versiooni ja lansseerinud mitu spetsialiseeritud API-d, kuid üldine lähenemine on jäänud muutumatuks. Uuendatud vahetusformaadid ja uus arhitektuur on võimaldanud API vigu kiiremini parandada.
Täna on MojeSklad API
Täna lahendab MojeSklad API palju ülesandeid:
- andmete vahetamine internetipoodide, raamatupidamissüsteemide, pankadega;
- arvutuste andmete ja aruannete saamine;
- kasutamine kliendirakenduste taga — meie mobiilirakendused ja töölauakassa töötavad API kaudu
- teavituste saatmine andmete muutumise kohta MoemSkladis — webhooks;
- telefoniteenused;
- loyaliteetsüsteemid.
API põhjal kirjutas meie tegevjuht Askar Rahimberdiev nelja tunni jooksul telegrammi boti, mis tõmbab API kaudu jääke:
Nüüd kuivad numbrid.
Siin on meie statistika vana REST API kohta:
- 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õigi MoemSklad API-dega:
- üle 70 integratsiooni (osa neist on saadaval siin );
- 8500 ettevõtet;
- 12 000 kasutajat;
- 46 miljonit päringut päevas;
- 2 TB/päevas väljaminevat liiklust.
Mis edasi
API arendamise plaanid on aktiivses arutelus. Püüame arvesse võtta kasutajate jagatud kogemusi. Mitte alati ja kõike ei õnnestu kohe teha, kuid uus API versioon, mis sisaldab mugavamaid metaandmeid ja vähem keerulist struktuuri, OAuth autentimiseks ning API rakenduste liidesesse integreerimiseks, on juba nurga taga.
Uudiste kohta saab jälgida spetsiaalsel saidil, mis on mõeldud MoimSkladiga integreerimise arendajatele: .
Allikas: habr.com
