A MyWarehouse API appeared 10 years ago. All this time we have been working on existing versions of the API and developing new ones. And several versions of the API have already been retired.
This article will cover a lot of topics: how the API was created, why it is needed for cloud services, what it offers to users, what pitfalls we encountered, and what we want to do next.
My name is Oleg Alexeev , I am the technical director and co-founder of MyWarehouse.
Why create an API for a service
Our clients, which number in the tens of thousands, actively use cloud solutions: banking, online stores, inventory management, and CRM. Once they connect to one, it becomes hard to stop. And now a fifth, eighth, tenth service makes the entrepreneur's work easier, but users transfer data between these cloud services manually. The work turns into a nightmare.
The obvious solution is to give users the ability to transfer data between cloud services. For example, importing and exporting data as files that can then be uploaded to the required service. Files are usually modified to fit the format of each service. This is more or less simple manual work, but as the number of these services grows, it becomes increasingly difficult to manage.
Therefore, the next step is the API. With it, the cloud service benefits from connecting multiple services at a single point. The emergence of such an ecosystem attracts new clients with additional opportunities. A product with new functionality becomes more profitable and useful.
If you create your own APIs, it attracts third-party sellers in the form of programmers who learn about your product through the API. They start building solutions based on the proposed API and earn money by automating their clients' tasks.
The MyWarehouse accounting system is built on simple processes. The main focus is on working with primary documents, allowing for receiving and shipping goods, and generating business reports based on primary data. There is also data transfer, for instance to cloud accounting, and acquiring data from banking systems or retail outlets. We also work with online stores: receiving information about products and sending inventory data.
A MeuArmazém API
A MeuArmazém é uma plataforma que, ao longo de 10 anos de uso de API, acumulou diversas integrações que permitem a troca de dados, interação com bancos, processamento de pagamentos e uso de telefonia externa.
No primeiro ano, disponibilizamos a opção de exportar quaisquer dados em formato XML. Naquela época, os usuários achavam muito mais compreensível e costumeiro manter os dados offline, em vez de em alguma nuvem, e nós oferecemos isso. A exportação era realizada manualmente a partir da interface. Portanto, não podíamos ainda chamar isso de API.
Na mesma época, iniciamos uma colaboração com a empresa Rusagro — eles já utilizavam um ERP 'maduro' para planejamento de produção e vendas, enquanto a carga dos vagões nas fábricas foi automatizada no MeuArmazém. Assim, surgiram as primeiras sementes de uma verdadeira API: a troca de dados entre nosso serviço e o ERP ocorria através do envio de um grande arquivo contendo informações sobre todos os tipos de documentos.
Esta era uma boa opção para a troca de dados em lote, mas com os documentos era necessário também transmitir suas dependências: informações sobre produtos, contrapartes e armazéns. Gerar essa confusão na exportação não era tão difícil, mas analisá-la na importação era bastante complicado, já que todos os dados chegavam em um único pacote: informações sobre novos documentos e sobre documentos já existentes.
A primeira API XML não durou muito — após dois anos, começamos a reestruturá-la. Desde o início de sua operação, cometemos alguns erros na construção da interface programática.
Como foi realizada a API XML: ilustração de um dos nossos arquitetos. A propósito, fique atento aos seus artigos.
Aqui estão nossos principais erros:
- A marcação JAXB foi feita diretamente nos beans de entidade. Para comunicação com o banco de dados, usamos Hibernate, e essa mesma marcação JAXB foi feita nos mesmos beans. Esse erro apareceu rapidamente: qualquer atualização na estrutura de dados exigia uma notificação urgente a todos que utilizavam a API, ou a construção de soluções alternativas que garantissem a compatibilidade com a estrutura de dados anterior.
- Az API kezdetben egy kiegészítésként fejlődött, és eredetileg nem határoztuk meg, hogy a termék melyik részét képezi. Arra sem gondoltunk, hogy az API valami fontos lenne, hogy szükség lenne a visszafelé kompatibilitás fenntartására az első ügyfelei számára. Egy időszakban az API felhasználóinak száma mindössze 5%-át tette ki a csekély összes felhasználónak, így rájuk nem figyeltünk. Az egyesített szűrés, amit valaha készítettünk, hozzájárult ahhoz, hogy minket backendként kezdtek használni. Ez a szűrés egyáltalán nem volt GraphQL, de hasonló volt — számos lekérdezési paraméteren keresztül működött. Ezzel a hatékony eszközzel a felhasználóknak nehéz volt ellenállni, és a lekérdezéseik közvetlenül az online boltjaik UI-jából indultak. A helyzet kellemetlen meglepetésként érkezett, mert egy ilyen szolgáltatás nyújtása más díjazást és egyéb megértést igényel az API mint termék tekintetében.
- Mivel az API nem mint fő termék fejlődött, az API dokumentációját a maradékeli alapelvek szerint készítettük és publikáltuk — visszafejlesztésen keresztül. Ez az út elég egyszerűnek és kényelmesnek tűnik, azonban ellentétes a szerződéses munkával. Ez akkor történik, amikor van egy komponens egy előre beállított működési sémával. A fejlesztő ennek megfelelően valósítja meg, a komponens tesztelésen megy keresztül, az ügyfél egy olyan terméket kap, amely megfelel az elemző elképzelésének. A visszafejlesztés viszont olyan terméket dob a piacra, amely csak egyszerűen létezik: akadályokkal, furcsa megoldásokkal és kerékpárokkal a szükséges funkcionalitás helyett.
- Az összes API-n keresztül érkező lekérdezés áramlását legfeljebb az Nginx vagy az alkalmazás szerver naplójaként lehetett elemezni. Ez nem tette lehetővé a szakterületek kiemelését, csak a felhasználók és előfizetők szerinti bontást. Ha nincs lehetőség az alkalmazások vagy ügyfelek regisztrálásának szabályozására, lehetetlenné válik a helyzet elemzése. Ez a probléma legkevésbé befolyásolta az API fejlődését, inkább a keresletének és funkcióinak megértéséről szól.
A második kísérlet: REST API
2010-ben próbáltunk egy online könyvelő rendszerrel, a BuhSofttal, adatcserélő rendszert építeni. Ez nem sikerült. Viszont az integrációs folyamat során megjelent egy teljes funkcionalitású API: egy REST-alapú adatcserélő szolgáltatás, amelyben nem voltak liberális megközelítések, mint a RPC hívások. Az API-val való kommunikációt a REST szabványos módjára hoztuk, ahol a kérés sorában a lényeg nevét adjuk meg, míg a végrehajtott műveletet az http-módszer határozza meg. Bevezettük a szűrést a lények frissítési ideje alapján, így a felhasználóknak lehetőségük nyílt a saját rendszereikkel való replikációra.
Ugyanebben az évben megjelent az API a raktári és termékállományok exportálására. A felhasználók számára hozzáférhetővé váltak az API-n keresztül a rendszer legértékesebb részei — a primer dokumentumok cseréje és a készlet- és önköltségadatok számítása.
2015 decemberében a RetailCRM közzétette az első külső könyvtárat, amely hozzáférést biztosított az API-nkhoz. Ezt meglehetősen aktívan használták, miközben növekedett a szolgáltatás népszerűsége is, és az API terhelése gyorsabban nőtt, mint a webes felület terhelése. Egyszer csak a növekedés ugrássá változott.
És ez az ugrás, amelyet a bal oldalon mutató nyíl jelez, teljes megdöbbenést okozott a mi API-nkat kiszolgáló szervernek. Egy hétig próbáltuk kideríteni, hogy ez a terhelés pontosan mit generál. Kiderült, hogy ezek azok a lekérdezések, amelyeket az ügyfelek front-endjei transzferek az API-nkra. Körülbelül 50 ügyfél fogyasztotta el az összes erőforrást. Ekkor megértettük egyik hibánkat — a teljesen hiányzó korlátokat.
Végül bevezettük a korlátot a párhuzamos lekérdezések számára. Egy fiókból legfeljebb két lekérdezést lehetett egyszerre megnyitni. Ez elegendő volt a replikációs módban való munkához az adatok csomagolt cseréjére. Azok számára, akik minket backendként kívántak használni, azóta többet kellett igazodniuk a tarifákhoz, mivel több fiók használatára is kötelezővé tettük a programjaikban.
Rendet rakunk
Már 2014 óta a meglévő API iránti kereslet a vállalkozás fontos részévé vált, és maga az API generálta a legnagyobb adatforgalmat az ügyfelekkel való adatcserében. 2015-ben elindítottuk az API rendezésére irányuló projektet. A JSON formátumot választottuk az XML helyett, és azt az előző verzió megvalósítása során feltárt jellemzők alapján kezdtük el felépíteni:
- Verziókezelési lehetőség. A verziókezelés lehetővé teszi új verziók fejlesztését anélkül, hogy az aktuális alkalmazást érintené, és ne zavarja a felhasználók munkáját.
- A felhasználó lehetősége, hogy lássa a metaadatokat a kapott válaszban.
- Nagy dokumentumok cseréjének lehetősége. Ha egy dokumentumot több mint 4-5 ezer tételnyi pozícióval dolgozunk fel, az problémát jelent a szervernek: hosszan tartó tranzakció, hosszú http-kérés. Kifejlesztettünk egy speciális mechanizmust, amely lehetővé teszi a dokumentum darabokban való frissítését és a dokumentum egyes pozícióinak kezelését, amelyek a szerverre küldhetők.
- Replikációs eszközök — ezek már a korábbi verzióban is jelen voltak.
- Terhelési korlátok — mint az előző verzióba hiba következményeként. Bevezettük a kérdések számának, párhuzamos kérések számának és egy ip-címről érkező kérések számának korlátozását.
Azóta két kisebb API verziót adtunk ki, és néhány speciális API-t indítottunk, de a megközelítés általában változatlan maradt. A frissített adatcsere-formátum és az új architektúra lehetővé tette a hibák gyorsabb javítását az API-ban.
A Módszerek API-ja ma
A Módszerek API-ja ma számos feladatot ellát:
- adatcsere internetes boltakkal, könyvelő rendszerekkel, bankokkal;
- számított adatok, jelentések beszerzése;
- backendként való használat kliensalkalmazások számára — mobil alkalmazásaink és desktop pénztárgépünk az API-n keresztül működik
- értesítések küldése a Módszerekben végrehajtott adatváltozásokról — webhooks;
- telefonálás;
- lojalitási rendszerek.
API-ink alapján a vezérigazgatónk, Askar Rakhimberdiev négy óra alatt megírta a telegram-botot, amely az API-n keresztül a készleteket szerzi be:
Most jöjjenek a száraz számok.
Íme a statisztikánk a régi REST API-val kapcsolatban:
- 400 cég;
- 600 felhasználó;
- 2 millió napi kérés;
- 200 GB/nap kimenő forgalom.
Íme a célra, amit elértünk a Módszerek összes API-jával:
- több mint 70 integráció (egyeseket itt meg lehet nézni );
- 8500 cég;
- 12 000 felhasználó;
- 46 millió napi kérés;
- 2 TB/nap kimenő forgalom.
Mi következik
Az API-fejlesztési tervek aktívviták alatt állnak. Igyekszünk figyelembe venni a felhasználóink tapasztalatait. Nem mindig és nem minden azonnal megvalósítható, de nincs messze egy új API-verzió, amely kényelmesebb metaadatokat és egyszerűbb struktúrát kínál, OAuth-ot az autentikációhoz, valamint API-t beágyazott alkalmazásokhoz.
A hírekről egy külön oldalról tájékozódhatsz, amely a MojSklad integrációs fejlesztők számára készült: .
Forrás: habr.com
