Першы API МайгоСклада з'явіўся 10 гадоў таму. Увесь гэты час мы працуем над існуючымі версіямі API і распрацоўваем новыя. А некалькі вэрсіяў API ужо пасьпелі пахаваць.
У гэтым артыкуле будзе шмат усяго: як стваралі API, навошта ён патрэбен хмарнаму сэрвісу, што дае карыстачам, на якія граблі мы паспелі наступіць і што жадаем рабіць далей.
Мяне клічуць Алег Аляксееў , я тэхнічны дырэктар і сузаснавальнік МайгоСклада.
Навошта рабіць API для сэрвісу
Нашы кліенты, а гэта дзясяткі тысяч прадпрымальнікаў, актыўна карыстаюцца хмарнымі рашэннямі: банкінгам, інтэрнэт-крамамі, таварным улікам, CRM. Падключыўся да аднаго - і ўжо цяжка спыніцца. І вось ужо пяты, восьмы, дзясяты сэрвіс робіць працу прадпрымальніка лягчэй, але дадзеныя паміж гэтымі хмарнымі сэрвісамі карыстачы пераносяць уручную. Праца ператвараецца ў кашмар.
Відавочнае рашэнне - даць карыстальнікам магчымасць перадаваць дадзеныя паміж хмарнымі сэрвісамі. Напрыклад, імпартаваць і экспартаваць дадзеныя як файлы, якія затым можна загрузіць у патрэбны сэрвіс. Файлы звычайна мяняюць пад фармат кожнага сэрвісу. Гэта больш-менш простая ручная праца, але з ростам колькасці гэтых сэрвісаў выконваць яе становіцца ўсё больш складана.
Таму наступны крок - API. З ім хмарны сэрвіс выйграе ад таго, што звязвае некалькі сэрвісаў у адной кропцы. З'яўленне такой экасістэмы прыцягвае новых кліентаў за рахунак дадатковых магчымасцяў. Прадукт з новым функцыяналам становіцца схаднейшым і карысным.
Калі ствараць уласныя праграмныя інтэрфейсы, гэта прыцягвае іншых прадажнікаў у выглядзе праграмістаў, якія ведаюць аб вашым прадукце дзякуючы API. Яны пачынаюць будаваць рашэнні на аснове прапанаванага API і зарабляюць грошы на аўтаматызацыі задач сваіх замоўцаў.
Уліковая сістэма МайгоСклада будуецца на простых працэсах. Галоўнае - праца з першаснымі дакументамі, магчымасць праводзіць прыёмку і адгрузку тавару, атрымліваць на аснове пяршоўкі справаздачы для бізнесу. Таксама ёсць перадача даных, напрыклад у хмарную бухгалтэрыю, і іх атрыманне з банкаўскіх сістэм або рознічных кропак. Яшчэ мы працуем з інтэрнэт-крамамі: атрымліваем звесткі аб таварах і адпраўляем дадзеныя аб рэштках.
Першы API МайгоСклада
За 10 гадоў працы МайгоСклада з API мы абраслі разнастайнымі інтэграцыямі, якія дазваляюць абменьвацца дадзенымі, працаваць з банкамі, праводзіць аплату і выкарыстоўваць знешнюю тэлефанію.
У першы год мы зрабілі магчымасць выгружаць любыя даныя ў фармаце XML. Тады карыстальнікам было куды больш зразумела і звыкла трымаць дадзеныя ў афлайне, а не ў нейкім там воблаку, і мы далі ім гэта. Выгрузка запускалася ручным экспартам з інтэрфейсу. Гэта значыць, API гэта яшчэ нельга было назваць.
Тады ж мы сталі супрацоўнічаць з кампаніяй Русагра – яны ўжо выкарыстоўвалі «дарослую» ERP для планавання вытворчасці і збыту, а вось загрузку вагонаў на заводах аўтаматызавалі ў Маім Складзе. Так у нас з'явіліся першыя зародкі сапраўднага API: абмен паміж нашым сэрвісам і ERP адбываўся шляхам перасылкі вялікага файла з дадзенымі па ўсіх тыпах дакументаў.
Гэта нядрэнны варыянт для пакетнага абмену дадзенымі, але разам з дакументамі даводзілася перадаваць іх залежнасці: звесткі аб таварах, контрагентах і складах. Такую звалку не так цяжка згенераваць пры экспарце, але даволі цяжка разбіраць пры імпарце, бо ў адным пакеце прыязджаюць усе звесткі: і пра новыя дакументы, і пра ўжо існуючыя.
Першы XML API пражыў нядоўга – праз два гады мы пачалі яго перабудову. Яшчэ на старце яго працы мы здзейснілі некалькі памылак пры пабудове праграмнага інтэрфейсу.
Як рабіўся XML API: ілюстрацыя ад аднаго з нашых архітэктараў. Дарэчы, чакайце яго артыкулаў.
Вось нашы асноўныя памылкі:
- JAXB-разметка была зроблена напрамую на entity beans. Для зносін з базай мы выкарыстоўваем Hibernate, і на гэтыя ж біны была зроблена JAXB-разметка. Гэтая памылка вылезла амаль адразу: любое абнаўленне структуры дадзеных прыводзіла да неабходнасці тэрміновага апавяшчэння ўсіх, хто выкарыстоўвае API, альбо пабудове мыліц, якія забяспечвалі б сумяшчальнасць з папярэдняй структурай дадзеных.
- API рос як нейкі дадатак, і першапачаткова мы не вызначылі, якую частку прадукта ён складае. Не думалі і над тым, ці з'яўляецца API нечым важным, ці трэба падтрымліваць зваротную сумяшчальнасць для першых яго кліентаў. На нейкі момант колькасць карыстальнікаў API складала каля 5% ад агульнай невялікай колькасці, і ўвагі на іх не звярталі. Зробленае ў свой час універсальная фільтрацыя прывяла да таго, што нас сталі выкарыстоўваць як бэкэнд. Фільтраванне гэтая была зусім не GraphQL, але нешта тыпу таго - працавала праз плойму параметраў радка запыту. З такой магутнай прыладай карыстачам было цяжка ўтрымацца, і на нас перавялі запыты так, што яны адпраўляліся напроста з UI іх інтэрнэт-крам. Сітуацыя стала непрыемнай неспадзеўкай, таму што падаванне такой паслугі павінна патрабаваць іншай тарыфікацыі і наогул іншага разумення самога API як прадукта.
- З-за таго, што API развіваўся не як асноўны прадукт, дакументацыя па API выраблялася і публікавалася па рэшткавым прынцыпе – праз рэверс-інжынірынг. Такі шлях здаецца дастаткова простым і зручным, але супярэчыць рабоце па кантракце. Гэта калі ёсць нейкі кампанент з прадусталяванай схемай працы. Распрацоўнік рэалізуе яго ў адпаведнасці з гэтай схемай і задачай, кампанент праходзіць тэсціраванне, кліент атрымлівае прадукт, які адпавядае задумцы аналітыка. Рэверс-інжынірынг жа на рынак выкідвае прадукт, які проста ёсць: з мыліцамі, дзіўнымі рашэннямі і веласіпедамі замест патрэбнага функцыяналу.
- Увесь струмень запытаў, які прыходзіў праз API, можна было прааналізаваць не больш як лог Nginx'а ці application server'а. Гэта не дазваляла вылучыць прадметныя вобласці, хіба што разбіць па карыстальніках і падпісчыкам. Калі няма магчымасці рэгуляваць рэгістрацыю дадатку або кліентаў, аналізаваць сітуацыю становіцца немагчыма. Гэтая праблема ў найменшай ступені паўплывала на развіццё API, яна больш пра разуменне яго запатрабаванасці і напоўненасці функцыяналам.
Спроба нумар два: REST API
У 2010 годзе мы спрабавалі пабудаваць сістэму абмену з анлайн-бухгалтэрыяй — БухСофтам. Не ўзляцела. Затое падчас інтэграцый з'явіўся паўнавартасны API: REST-сэрвіс абмену, дзе адсутнічалі вольнасці накшталт зваротаў да аперацый у выглядзе RPC выклікаў. Усе зносіны з API былі прыведзены да стандартнага для рэста рэжыму: у радку запыту змяшчаецца назва сутнасці, а аперацыя, якая з ёй праводзіцца, задаецца з дапамогай http-метаду. Мы дадалі фільтраванне па моманте абнаўлення сутнасцяў, і ў карыстачоў з'явілася магчымасць будаваць рэплікацыю са сваімі сістэмамі.
У тым жа годзе з'явіўся API для выгрузкі складскіх і таварных астаткаў. Для карыстальнікаў сталі даступныя праз API найбольш каштоўныя часткі сістэмы - абмен першаснымі дакументамі і разліковыя дадзеныя па рэштках і сабекошце тавараў.
У снежні 2015 года RetailCRM апублікаваў першую іншую бібліятэку для доступу да нашага API. Яе сталі даволі актыўна выкарыстоўваць, пры гэтым расла папулярнасць сэрвісу ў цэлым, нагрузка на API расла хутчэй нагрузкі на вэб-інтэрфейс. Аднойчы рост ператварыўся ў скачок нагрузкі.
І гэты скок, на які паказвае стрэлка злева, прывёў у поўнае здзіўленне сервер, які абслугоўвае наш API. Тыдзень мы разбіраліся, што менавіта гэтую нагрузку генеруе. Аказалася, што гэта тыя самыя запыты, якія транслююцца на наш API з франтоў у кліентаў. Усе з'елі каля 50 кліентаў. Тут-то мы і зразумелі адну са сваіх памылак - поўная адсутнасць лімітаў.
У выніку мы ўвялі ліміт на колькасць адначасовых запытаў. З аднаго ўліку стала можна адначасова адкрываць не больш за два запыты. Гэтага дастаткова для працы ў рэжыме рэплікацыі для абмену дадзенымі ў пакетным рэжыме. А тыя, хто хацеў выкарыстоўваць нас як бэкэнд, з гэтага моманту былі вымушаныя больш адпавядаць тарыфам, бо ўвялі ў свае праграмныя сродкі працу па некалькіх уліках.
Прыводзім у парадак
Ужо з 2014 года попыт на існуючы API стаў важнай часткай бізнэсу, а сам API генераваў самы вялікі аб'ём дадзеных у абмене дадзенымі з кліентамі. У 2015 годзе мы запусцілі праект прывядзення API у парадак. Выбралі ў якасці фармату JSON замест XML і сталі будаваць яго на аснове асаблівасцяў, якія выявілі пры рэалізацыі папярэдняй версіі:
- Магчымасць кіраваць версіямі. Версіянаванне дазваляе распрацоўваць новую версію, не закранаючы існуючы дадатак і не парушаючы працу карыстальнікаў.
- Магчымасць карыстачу бачыць метададзеныя ў самым адказе, які ён атрымлівае.
- Магчымасць абмену вялікімі дакументамі. Калі мы апрацоўваем дакумент з колькасцю пазіцый больш за 4-5 тысяч, гэта становіцца праблемай для сервера: доўгая транзакцыя, доўгі http-запыт. Пабудавалі спецыяльны механізм, які дазваляе абнаўляць дакумент часткамі і кіраваць асобнымі пазіцыямі гэтага дакумента, адпраўляючы іх на сервер.
- Інструменты для рэплікацыі - былі і ў папярэдняй версіі.
- Ліміты па нагрузцы - як спадчына грабляў, на якія наступілі ў папярэдняй версіі. Увялі ліміты на колькасць запытаў у прамежак часу, колькасць паралельных запытаў і запытаў з аднаго ip-адрасу.
З таго моманту мы выпусцілі дзве мінорныя версіі API і запусцілі некалькі спецыялізаваных API, але ў цэлым падыход застаўся без змен. Абноўлены фармат абмену і новая архітэктура дазволілі выпраўляць недахопы ў API куды хутчэй.
API МайгоСклада сёння
Сёння API МайгоСклада вырашае шмат задач:
- абмен дадзенымі з інтэрнэт-крамамі, уліковымі сістэмамі, банкамі;
- атрыманне разліковых даных, справаздач;
- выкарыстанне ў якасці бэкенда для кліенцкіх прыкладанняў — нашы мабільныя прыкладанні і дэсктопная каса працуюць праз API
- адпраўка апавяшчэнняў аб зменах дадзеных у МаімСкладзе - webhooks;
- тэлефанія;
- сістэмы лаяльнасці.
На аснове API наш гендырэктар Аскар Рахімбердыеў за чатыры гадзіны напісаў тэлеграм-бот, які цягае праз API рэшткі:
Цяпер сухія лічбы.
Вось наша статыстыка па старым REST API:
- 400 кампаній;
- 600 карыстальнікаў;
- 2 млн запытаў у суткі;
- 200 Гб/суткі выходнага трафіку.
А вось да чаго мы дашлі па ўсіх API МайгоСклада:
- больш за 70 інтэграцый (частку з іх можна паглядзець тут );
- 8500 кампаній;
- 12 000 карыстальнікаў;
- 46 млн запытаў у суткі;
- 2 Тб/суткі выходнага трафіку.
Што далей
Планы па развіццю API знаходзяцца ў актыўным абмеркаванні. Мы імкнемся ўлічваць досвед эксплуатацыі, якім нас забяспечваюць карыстачы. Не заўсёды і не ўсё атрымліваецца рабіць адразу, але не за гарамі новая версія API з зручнейшымі метададзенымі і меней разложыстый структурай, OAuth для аўтэнтыфікацыі, API для ўбудавальных у інтэрфейс прыкладанняў.
Сачыць за навінамі можна на спецыяльным сайце для распрацоўшчыкаў інтэграцый з МаімСкладам: .
Крыніца: habr.com
